PureBasic Docs- Ideas/Help needed for a "We start" chapter!?

[IdeasVacuum]

Hi Andre

I think consistency is helpful to the new User, but using $ instead of .s is not consistent with the declaration of other types. Missing-off the .i is inconsistent too..........

Also, including a prefix is common practice in other languages, so that you always know the value type that can be assigned. For example:

Declare an integer: MyNumVal
Declare a double: MyValNum.d

In the code, you do not 'see' the value type that can be assigned to these variables.

Better therefore:

Declare an integer: iMyNumVal.i
Declare a double: dMyValNum.d

[Andre]

@IdeasVacuum: you made good points, I think. Netherless are the meanings of Fred & Timo also important to me.

Other meanings?

[Little John]

@IdeasVacuum: you made good points, I think. Netherless are the meanings of Fred & Timo also important to me.

Other meanings?

My opinion is, that you probably are talking about opinions, not meanings.

[Andre]

My opinion is, that you probably are talking about opinions, not meanings.

Of, course! My english is far from being perfect...

[Andre]

Before starting to include these "Beginners / We start..." chapter into the manual, it would be good to have some more opinions from the users....

These were freak's suggestions:

So I need to change all code examples a bit, according to the following "rules":
- avoid hungarian notation like "strString", just "String$" or a (longer) meaningful name should do it
- use String variables always with $ (instead of .s)
- type suffix at Define in lower chars, like "Define.l" (instead of "Define.L")
- Integer variables without type suffix (because the standard .i type should be used instead of long .l)
- define Floats with .f or .d, then normally use them
- examples for meaningful (variable) names: 'CamelCase': "FileName", "EventType", etc.

Beside this, what would you prefer:
1) A single (but long) site with all topics, with a "contents" area at the top, from which you have links to each topic, and can jump back to the contents area from each topic... (would be easier to print...)
2) A separate section in the manual, with each topic on a single site, which are linked together...

Thanks!

[blueznl]

Declare an integer: iMyNumVal.i
Declare a double: dMyValNum.d

I beg to disagree. The postfix is clear enough. We're programming in basic, not in C. Though, admittedly, it wouldn't matter too much

(I've always found prefix typing very confusing, as I'm used to all lowercase variable names, and CaMeLiNg isn't my thing. To each his own, I guess...)

I also rather prefer the use of .s instead of $, it's more consistent with other typing. As for CaMeLiNg... yeah, it makes sense to use it, even if I personally don't

[Thade]

Declare an integer: MyNumVal
Declare a double: MyValNum.d

In the code, you do not 'see' the value type that can be assigned to these variables.

Better therefore:

Declare an integer: iMyNumVal.i
Declare a double: dMyValNum.d

This is very last thing I want to see.
I have 100s of little Programs, which from time to time are updated. And I bet for 100s of PB Users this is alike. Shall we all rewrite them?
Even a discussion about such an attempt is a waste of time. This is Basic and the basics of the language shall stay as they are.
No-one stops you to add the prefixes ... but as a must it is out of discussion, I hope.

I also rather prefer the use of .s instead of $, it's more consistent with other typing. As for CaMeLiNg... yeah, it makes sense to use it, even if I personally don't

I agree with that. But as long as both exist - no problem.

[Andre]

I've reviewed all the contributions (thanks again spikey!), tested and reworked the examples (being aware of most of the "rules", Timo has posted), and finally included the "beginners" or "user guide" into the reference manual, including a lot of links to the commands/keywords used in the guide....

The current status of the project, how it looks, when included into the reference manual of PureBasic:
=> http://www.purearea.net/pb/english/manu ... rview.html

This is the overview of topics included for now:

Topics in this chapter:
- First steps
- Variables and Processing of variables
- Constants
- Decisions & Conditions
- Loops
- String Manipulation [missing]
- Storing data in memory
- Input & Output
- Displaying text output (Console)
- Building a graphical user interface (GUI)
- Displaying graphics output & simple drawing
- Structuring code in Procedures
- Compiler directives (for different behaviour on different OS)
- Reading and writing files
- Memory access
- Other Compiler keywords [missing]
- Other Library functions [missing]
- Advanced functions [missing]
- Some Tipps & Tricks [one example until now]
- ......

If you have any further suggestions, or best of all: do you have contributions to the missing topics, you're welcome to post them here! Thank you very much

[IdeasVacuum]

Looks really good Andre.

In places longs are used where ints should be (re Freak's blog on apps for 64bit).

[Andre]

@IdeasVacuum: thanks for the note about longs/integers.

As I'm currently doing the german translation of the user guide for the PB4.61 final release, feel free to point me to needed changes in this chapter. Thanks!


@All: anyone with contributions to the missing contents (see above or first post)? Thank you!

[Andre]

Anyone with ideas for the missing chapters, especially "String manipulation"?

[Andre]

As I've nearly finished also the german translation of this new beginners chapter, there is a suggestion about implementing also a "beginners chapter for 3D stuff" here:
http://www.purebasic.fr/english/viewtop ... 08&start=5

[Andre]

Latest status of the project (in finished PB doc format) is now online.
See the already known link: http://www.purearea.net/pb/english/manu ... rview.html

Any further help is welcome!

[spikey]

Andre,
I've revised this example as I discovered that the window layout wasn't very good on Ubuntu Linux.

Code: Select all

; Window
Enumeration
  #WinHarmonic
EndEnumeration

; Gadgets
Enumeration
  #txtPlot1
  #cboPlot1
  #txtPlot2
  #cboPlot2
  #imgPlot
EndEnumeration

; Image
Enumeration
  #drgPlot
EndEnumeration

; Image dimensions are used in several places so define constants.
#imgPlotX = 8
#imgPlotY = 40
#imgPlotW = 745
#imgPlotH = 645

; Event variables
Define.l Event, EventWindow, EventGadget, EventType, EventMenu

; Implementation
Procedure CreateWindow()
  ; Creates the window and gadgets.  
  
  If OpenWindow(#WinHarmonic, 30, 30, #imgPlotW + 20, #imgPlotH + 55, "Harmonics", #PB_Window_SystemMenu | #PB_Window_MinimizeGadget | #PB_Window_TitleBar)
    
    ; This is a non-visual gadget used to draw the image, later its contents will be displayed in #imgPlot.
    CreateImage(#drgPlot, #imgPlotW - 5, #imgPlotH - 5, 24)
    
    ; Label for the Plot 1 combo.
    TextGadget(#txtPlot1, 2, 5, 50, 25, "Plot 1:")
    
    ; The Plot 1 combo.
    ComboBoxGadget(#cboPlot1, 55, 5, 150, 25)
    AddGadgetItem(#cboPlot1, 0, "Sin(X)")
    AddGadgetItem(#cboPlot1, 1, "Sin(X * 2)")
    AddGadgetItem(#cboPlot1, 2, "Sin(X * 3)")
    AddGadgetItem(#cboPlot1, 3, "Sin(X * 4)")
    AddGadgetItem(#cboPlot1, 4, "Sin(X * 5)")
    AddGadgetItem(#cboPlot1, 5, "Sin(X * 6)")
    
    ; Select Sin(X)
    SetGadgetState(#cboPlot1, 0)
    
    ; Label for the Plot 2 combo.
    TextGadget(#txtPlot2, 230, 5, 50, 25, "Plot 2:")
    
    ; The Plot 2 combo.
    ComboBoxGadget(#cboPlot2, 280, 5, 150, 25)
    AddGadgetItem(#cboPlot2, 0, "Sin(X)")
    AddGadgetItem(#cboPlot2, 1, "Sin(X * 2)")
    AddGadgetItem(#cboPlot2, 2, "Sin(X * 3)")
    AddGadgetItem(#cboPlot2, 3, "Sin(X * 4)")
    AddGadgetItem(#cboPlot2, 4, "Sin(X * 5)")
    AddGadgetItem(#cboPlot2, 5, "Sin(X * 6)")
    
    ; Select Sin(X * 2), otherwise the initial display is a bit uninteresting.
    SetGadgetState(#cboPlot2, 1)
    
    ; The visual image gadget on the window.
    ImageGadget(#imgPlot, #imgPlotX, #imgPlotY, #imgPlotW, #imgPlotH, 0, #PB_Image_Border)
    
  EndIf
  
EndProcedure

Procedure PlotAxes()
  ; Draws the axes on the image #drgPlot.
  
  ; Send drawing commands to #drgPlot.
  StartDrawing(ImageOutput(#drgPlot))
  
  ; Draw a white background.
  Box(0, 0, ImageWidth(#drgPlot), ImageHeight(#drgPlot), RGB(255, 255, 255))
  
  ; Draw the axes in black.
  Line(1, 1, 1, ImageHeight(#drgPlot) - 2, RGB(0, 0, 0))
  Line(1, (ImageHeight(#drgPlot) - 2) /2, ImageWidth(#drgPlot) -2, 1, RGB(0, 0, 0))
  
  ; Finished drawing.
  StopDrawing()
EndProcedure

Procedure PlotLegend(alngPlot1, alngPlot2)
  ; Draws the legend on the image #drgPlot.
  
  Protected.s strFunc1, strFunc2, strLabel1, strLabel2, strLabel3
  
  ; Set label text 1.
  If alngPlot1 = 0 
    strFunc1 = "Sin(X)"
    
  Else
    strFunc1 = "Sin(X * " + StrU(alngPlot1 + 1) + ")"
    
  EndIf
  
  ; Set label text 2.
  If alngPlot2 = 0 
    strFunc2 = "Sin(X)"
    
  Else
    strFunc2 = "Sin(X * " + StrU(alngPlot2 + 1) + ")"
    
  EndIf
  
  ; Set label text.
  strLabel1 = "Y = " + strFunc1
  strLabel2 = "Y = " + strFunc2
  strLabel3 = "Y = " + strFunc1 + " + " + strFunc2 
  
  ; Draw legend.
  StartDrawing(ImageOutput(#drgPlot))
  
  ; Box.
  DrawingMode(#PB_2DDrawing_Outlined)
  Box(20, 10, TextWidth(strLabel3) + 85, 80, RGB(0, 0, 0))
  
  ; Label 1.
  Line(30, 30, 50, 1, RGB(0, 0, 255))
  DrawText(95, 22, strLabel1, RGB(0, 0, 0), RGB(255, 255, 255))
  
  ; Label 2.
  Line(30, 50, 50, 1, RGB(0, 255, 200))
  DrawText(95, 42, strLabel2, RGB(0, 0, 0), RGB(255, 255, 255))
  
  ; Label 3.
  Line(30, 70, 50, 1, RGB(255, 0, 0))
  DrawText(95, 62, strLabel3, RGB(0, 0, 0), RGB(255, 255, 255))
  
  StopDrawing()
  
EndProcedure

Procedure PlotFunction(alngPlot1, alngPlot2)
  ; Draws the waveforms on the image #drgPlot.
  
  Protected.l lngSX, lngEX
  Protected.f fltRad1, fltRad2, fltSY1, fltEY1, fltSY2, fltEY2, fltSY3, fltEY3
  
  StartDrawing(ImageOutput(#drgPlot))
  
  ; Set initial start points for each wave.
  lngSX = 1
  fltSY1 = ImageHeight(#drgPlot) / 2
  fltSY2 = fltSY1
  fltSY3 = fltSY1
  
  ; Plot wave forms.
  For lngEX = 1 To 720
    ; Sine function works in radians, so convert from degrees and calculate sine.
    
    ; Function 1
    If alngPlot1 = 0 
      fltRad1 = Sin(Radian(lngEX))
    Else
      ; If the function should have a multiplier, account for this.
      fltRad1 = Sin(Radian(lngEX) * (alngPlot1 + 1))
    EndIf
    
    ; Function 2
    If alngPlot2 = 0 
      fltRad2 = Sin(Radian(lngEX))
    Else
      fltRad2 = Sin(Radian(lngEX) * (alngPlot2 + 1))
    EndIf
    
    ; Plot function 1 in blue.
    ; Calculate end Y point.
    fltEY1 = (ImageHeight(#drgPlot) / 2) + (fltRad1 * 100)
    ; Draw a line from the start point to the end point.
    LineXY(lngSX, fltSY1, lngEX, fltEY1, RGB(0, 0, 255))
    ; Update the next start Y point to be the current end Y point.
    fltSY1 = fltEY1
    
    ; Plot function 2 in green.
    fltEY2 = (ImageHeight(#drgPlot) / 2) + (fltRad2 * 100)
    LineXY(lngSX, fltSY2, lngEX, fltEY2, RGB(0, 255, 200))
    fltSY2 = fltEY2
    
    ; Plot harmonic in red.
    fltEY3 = (ImageHeight(#drgPlot) / 2) + ((fltRad1 + fltRad2) * 100)
    LineXY(lngSX, fltSY3, lngEX, fltEY3, RGB(255, 0, 0))
    fltSY3 = fltEY3
    
    ; Update the start X point to be the current end X point.
    lngSX = lngEX
  Next lngEX
  
  StopDrawing()
  
EndProcedure

;- Main
CreateWindow()
PlotAxes()
PlotLegend(GetGadgetState(#cboPlot1), GetGadgetState(#cboPlot2))
PlotFunction(GetGadgetState(#cboPlot1), GetGadgetState(#cboPlot2))

; Reload the image gadget now drawing is complete.
ImageGadget(#imgPlot, #imgPlotX, #imgPlotY, #imgPlotW, #imgPlotH, ImageID(#drgPlot), #PB_Image_Border)

;- Event loop
Repeat
  Event = WaitWindowEvent()
  EventWindow = EventWindow()
  EventGadget = EventGadget()
  EventType = EventType()
  
  Select Event
    Case #PB_Event_Gadget
      If EventGadget = #txtPlot1 Or EventGadget = #txtPlot2
        ; Do nothing.
      ElseIf EventGadget = #imgPlot
        ; Do nothing.
      ElseIf EventGadget = #cboPlot1 Or EventGadget = #cboPlot2
        ; If one of the combo boxes changed, redraw the image.
        PlotAxes()
        PlotLegend(GetGadgetState(#cboPlot1), GetGadgetState(#cboPlot2))
        PlotFunction(GetGadgetState(#cboPlot1), GetGadgetState(#cboPlot2))
        ImageGadget(#imgPlot, #imgPlotX, #imgPlotY, #imgPlotW, #imgPlotH, ImageID(#drgPlot), #PB_Image_Border)
      EndIf
    Case #PB_Event_CloseWindow
      If EventWindow = #WinHarmonic
        CloseWindow(#WinHarmonic)
        Break
      EndIf
  EndSelect
ForEver

[oldefoxx]

I use Google a lot to search out points of interest related to PureBasic. For instance,
I might use the phrase "purebasic console" to see if I can find anything anywhere that
relates to both purebasic and to console. If I want to know if there is anything on
the forums, I might enter instead "site:www.purebasic.fr/english/ console".

Using search engines in this manner, I come onto many things that I would have missed
otherwise. I found Horst S. website and he has a lot of good stuff there for downloading.
And he is not the only one.

My thought is that you should devote a bit of a Beginner's Book to the notion of searching
for helpful code, downloading it or copying it (say out of the Help files) into their own
file(s), and how Include files can be used to make that code a part of any program in the
the future where they might want to make use of it.