Examples for Documentation

[AZJIO]

I did not know in which section to create a topic, since this is not a mistake, and this is also not suitable for the "Feature Requests and Wishlists" topic. There is an idea to make examples on the page where they are not, but they are expected.

If the example is large, then you can link to the example page.

EnableGadgetDrop

Code: Select all

#Window = 0
Enumeration Gadget
	#str0
	#edr0
EndEnumeration

If OpenWindow(#Window, 0, 0, 500, 200, "Drop File Here", #PB_Window_SystemMenu | #PB_Window_ScreenCentered)

	StringGadget(#str0, 10, 10, 500 - 20, 30, "")
	EditorGadget(#edr0, 10, 50, 500 - 20, 140)
	
	EnableGadgetDrop(#str0, #PB_Drop_Files, #PB_Drag_Copy)
	EnableGadgetDrop(#edr0, #PB_Drop_Files, #PB_Drag_Copy)

	Repeat
		Select WaitWindowEvent()
			Case #PB_Event_GadgetDrop
				Select EventGadget()
					Case #str0 ; gadgets that received a file/folder drag and drop event
						If Not FindString(EventDropFiles(), Chr(10))
							SetGadgetText(#str0, EventDropFiles())
						EndIf
					Case #edr0
						SetGadgetText(#edr0, EventDropFiles())
				EndSelect
			Case #PB_Event_CloseWindow
				CloseWindow(#Window)
				End
		EndSelect
	ForEver
EndIf

ResizeGadget

Code: Select all

#Window = 0
Enumeration Gadget
	#edr0
	#btn0
EndEnumeration

Define ww = 220
Define wh = 100

If OpenWindow(#Window, 0, 0, ww, wh, "Resize the window", #PB_Window_SystemMenu | #PB_Window_ScreenCentered | #PB_Window_SizeGadget)
	WindowBounds(0, ww, wh, #PB_Ignore, #PB_Ignore)

	EditorGadget(#edr0, 10, 10, ww - 20, wh - 60)
	ButtonGadget(#btn0, 10, wh - 40, ww - 20, 30, "Button")

	Repeat
		Select WaitWindowEvent()
			Case #PB_Event_SizeWindow
				wh = WindowHeight(#Window) 
				ww = WindowWidth(#Window) 
				ResizeGadget(#edr0, #PB_Ignore, #PB_Ignore, ww - 20, wh - 60) 
				ResizeGadget(#btn0, #PB_Ignore, wh - 40, ww - 20, #PB_Ignore) 
			Case #PB_Event_CloseWindow
				CloseWindow(#Window)
				End
		EndSelect
	ForEver
EndIf

[Janni]

I also think it would be great with more examples (both easier and more complex examples). Sometimes the examples provides are above my level of competence.
What if ALL features would at the bottom of the page link to a wiki page (or similar) where everyone can contribute ?

[AZJIO]

You can use as examples in one of the ExamineDirectory(), NextDirectoryEntry(), DirectoryEntryType(), DirectoryEntryName(), FinishDirectory() functions other search methods, such as recursive:

Code: Select all

Procedure FileSearch(List Files.s(), dir.s, mask.s = "")
  Protected name.s, id
  
  If Right(dir, 1) <> #PS$
    dir + #PS$
  EndIf

  id = ExamineDirectory(#PB_Any, dir, "")
  If id
    While NextDirectoryEntry(id)
      name = DirectoryEntryName(id)
      If name = "." Or name = ".."
        Continue
      EndIf
      If DirectoryEntryType(id) = #PB_DirectoryEntry_Directory ; if the path is a folder
        FileSearch(Files(), dir + name + "\", mask) ; recursive call to subfolder
      ElseIf (Not Asc(mask) Or GetExtensionPart(name) = mask) And AddElement(Files())
        Files() = dir + DirectoryEntryName(id)
      EndIf
    Wend
    FinishDirectory(id)
  EndIf
EndProcedure

Define NewList Files.s()
FileSearch(Files(), GetTemporaryDirectory(), "exe") ; empty string to find all files

ForEach Files()
  Debug Files()
Next

GetUserDirectory()

Code: Select all

For i = 0 To 9
	Debug GetUserDirectory(i)
Next

RunProgram()

Code: Select all

; === Windows ===
RunProgram("hh.exe", Chr(34) + "help.chm::/html/index.htm" + Chr(34), "") ; open help file
RunProgram("explorer.exe", "/select," + #PB_Compiler_File, "") ; open explorer by selecting file

; === Linux ===
tmp$ = "/usr/share/help/ru/myprog/index.html"
RunProgram("xdg-open", tmp$, GetPathPart(tmp$)) ; open help file

[Andre]

I have added following example codes:
- EnableGadgetDrop (in a bit simplified form)
- ResizeGadget (- " - )
- GetUserDirectory (but in a more simplified form, using the PB constants)
- FileSearch.pb as a new separate example code (linked on main page of File library)

Thanks for your suggestions!

Example for RunProgram not used for now, there should be a MacOS version too I think.

[AZJIO]

You will say that this is only for Windows and it repeats the existing example. But it will help someone to understand at the same time how the command is used "cmd.exe dir", will help others to get a list of files or folders, depending on the keys. And you have free space for other functions (AvailableProgramOutput, ProgramRunning, etc.).
Initially I wanted to make an example for ReadProgramData, but this function is not appropriate for the command "cmd.exe dir".
ReadProgramString

Code: Select all

; Windows only
Define hProg, Output$
hProg = RunProgram(GetEnvironmentVariable("ComSpec"), ; cmd.exe
                      "/u /c (DIR " + Chr(34) + #PB_Compiler_Home + "\SDK\DocMaker" + Chr(34) + " /B /S /A-D)", "",
                      #PB_Program_Open | #PB_Program_Read | #PB_Program_Error | #PB_Program_Unicode | #PB_Program_Hide)
Output$ = ""
If hProg
	While ProgramRunning(hProg)
		If AvailableProgramOutput(hProg)
			Output$ + ReadProgramString(hProg) + Chr(13)
		EndIf
	Wend
	Output$ + Chr(13) + Chr(13)
	Output$ + "Exitcode: " + Str(ProgramExitCode(hProg))

	CloseProgram(hProg)
EndIf

MessageRequester("Output", Output$)

The EnvironmentVariableName and EnvironmentVariableValue functions do not have examples, you can add an "Example" subsection and make a link to ExamineEnvironmentVariables in it, then the user can always go to the example where this function is used.

ProgramParameter
It's too simple and uninteresting, but it seems to me that there should be examples for all functions. Perhaps "Select" + "MessageRequester" will do here

Code: Select all

Define style
If ProgramParameter() = "\f"
	style = #PB_Window_Maximize
EndIf

If OpenWindow(0, 0, 0, 220, 100, "Example...", #PB_Window_SystemMenu | #PB_Window_ScreenCentered | style)
	Repeat : Until WaitWindowEvent() = #PB_Event_CloseWindow
EndIf

[Axolotl]

Hi guys,

nice examples.

This just reminds me of the Purebasic Wiki topic, which apparently - like many attempts - also ends as a dead end.
I think of CodeArchive, Github Rebirth, and so on. Unfortunately, the whole thing lives from participation.
And very important: It should not be a criticism, but my thoughts as a suggestion...

Here are a few links as a reminder of the WIKI topic
/1/ Main Page of Purebasic Wiki
/2/ Thread about PureBasic Wiki
/3/ Thread about PureBasic-Reference-Wikipedia

[Janni]

To be fair, we are a small community and the WIKI is just a few months old.
I think many are not aware of it and It will take time.

Maye we all can change our signature ?

[AZJIO]

To create the most productive file, you need to have an example on the function description page. You press the F1 hotkey and immediately get a response, without additional transitions somewhere else. The help file is the main source of information. If the user sees how the function is used, why should he watch something else? If it's a high-quality module function that isn't intended to demonstrate any function and is difficult to understand, then you can make a repository of interesting things. But my suggestion is to show how to use the function in a small code, where the user will not stop to study the code for 2 hours, but will simply see the call and the guaranteed result, confirming the successful operation of the function.

[Andre]

To create the most productive file, you need to have an example on the function description page. You press the F1 hotkey and immediately get a response, without additional transitions somewhere else. The help file is the main source of information. If the user sees how the function is used, why should he watch something else? If it's a high-quality module function that isn't intended to demonstrate any function and is difficult to understand, then you can make a repository of interesting things. But my suggestion is to show how to use the function in a small code, where the user will not stop to study the code for 2 hours, but will simply see the call and the guaranteed result, confirming the successful operation of the function.

In general I agree with your suggestions/arguments... but which (smaller) examples should be included in the command descriptions, which (bigger) examples separately in the 'Examples' folder, and which more specifically (or maybe OS-specific) are probably something for a PureBasic WIKI... is something Fred has to decide and to comment here.

[AZJIO]

ScintillaSendMessage

Code: Select all

#Window = 0
#Sci = 0
#num_indicator = 0

Define *Text, nLine, start, length

If Not InitScintilla()
	End
EndIf

If OpenWindow(#Window, 0, 0, 330, 90, "ScintillaGadget", #PB_Window_SystemMenu | #PB_Window_ScreenCentered)
	ScintillaGadget(#Sci, 5, 5, 320, 80, 0)
	*Text = UTF8("This is a simple ScintillaGadget with text..." + #LF$ + "More text" + #LF$ + "Even more text!")
	ScintillaSendMessage(#Sci, #SCI_SETTEXT, 0, *Text)
	FreeMemory(*Text)
	ScintillaSendMessage(#Sci, #SCI_INDICSETSTYLE, #num_indicator, #INDIC_STRAIGHTBOX) ; first indicator with style 8 (0-19)
	ScintillaSendMessage(#Sci, #SCI_INDICSETFORE, #num_indicator, #Red)				; first indicator with red color
	ScintillaSendMessage(#Sci, #SCI_SETINDICATORCURRENT, #num_indicator, #INDIC_STRAIGHTBOX) ; makes the indicator current
	ScintillaSendMessage(#Sci, #SCI_INDICSETUNDER, #num_indicator, 1)						  ; indicator under the text, i.e. doesn't obscure it
	ScintillaSendMessage(#Sci, #SCI_INDICSETALPHA, #num_indicator, 127)					  ; Transparency
	; ScintillaSendMessage(#Sci, #SCI_INDICGETOUTLINEALPHA, #num_indicator, 255) ; Border transparency
	nLine = 1	; line number starts from 0
	start = ScintillaSendMessage(#Sci, #SCI_POSITIONFROMLINE, nLine)
	length = ScintillaSendMessage(#Sci, #SCI_GETLINEENDPOSITION, nLine) - start
	ScintillaSendMessage(#Sci, #SCI_INDICATORFILLRANGE, start, length) ; start and length
	; ScintillaSendMessage(#Sci, #SCI_INDICATORFILLRANGE, 46, 9) ; start and length
	Repeat : Until WaitWindowEvent() = #PB_Event_CloseWindow
EndIf

Chr
Here is an example of practical symbols that can be used as an icon on a button, as well as a loop showing the output of Latin letters.

Code: Select all

Debug Chr($2630) ; ☰
Debug Chr($25BC) ; ▼
For i = 65 To 90
    Debug Chr(i)
Next

FindString
The one-line example follows the syntax in the title, so you can show a loop using position.

Code: Select all

Define String$ = "This is a simple line...."
Define Position, Last

Repeat
	Last = Position
	Position = FindString(String$ , "i", Position + 1)
	Debug Position
Until Not Position

Debug Last

There are many examples in the French help file that are not in the English help. For example, look at the "FileSystem" section, in English there is almost no example there, but in French there are examples on every page.

WritePreferenceInteger
The peculiarity of the example is the absence of groups. That is, if the program has a small number of parameters, then you don’t have to create a group name.

Code: Select all

CreatePreferences(GetTemporaryDirectory()+"test.ini")
WritePreferenceInteger("x", 35)
WritePreferenceInteger("y", 46)
WritePreferenceInteger("w", 200)
WritePreferenceInteger("h", 100)
ClosePreferences()

OpenPreferences(GetTemporaryDirectory()+"test.ini")
Debug ReadPreferenceInteger("x", 0)
Debug ReadPreferenceInteger("y", 0)
Debug ReadPreferenceInteger("w", 400)
Debug ReadPreferenceInteger("h", 600)
ClosePreferences()

WritePreferenceString
Another way to use "Preferences" in a non-standard way

Code: Select all

; Use keys as data. In this case, the data must be unique and not duplicated.
CreatePreferences(GetTemporaryDirectory()+"ColorList.ini", #PB_Preference_NoSpace)
WritePreferenceString("FF0000", "")
WritePreferenceString("00FF00", "")
WritePreferenceString("0000FF", "")
WritePreferenceString("FF00FF", "")
ClosePreferences()

OpenPreferences(GetTemporaryDirectory()+"ColorList.ini")
ExaminePreferenceKeys()
While  NextPreferenceKey()
    Debug PreferenceKeyName()
Wend
ClosePreferences()

ExaminePreferenceGroups
Isn't it better to use "Debug"?

Code: Select all

MessageRequester("Groups", PreferenceGroupName())

ExaminePreferenceKeys
Isn't it better to use "Debug"? The loop and MessageRequester force me to click "OK" several times (4).

Code: Select all

MessageRequester("Key group 'Window'", PreferenceKeyName() + " = " + PreferenceKeyValue())

UncompressPackFile
Example with real files

Code: Select all

UseZipPacker()

Define Path$ = "C:\ProgramData\PureBasic\Examples\Sources\Data\"
If CreatePack(0, "C:\ProgramData\PureBasic\Examples\MyCompressedFiles.zip")
	AddPackFile(0, Path$ + "world.png", "world.png")
	AddPackFile(0, Path$ + "test.pref", "test.pref")
	AddPackFile(0, Path$ + "CdPlayer.ico", "CdPlayer.ico")
	AddPackFile(0, Path$ + "Background.bmp", "Background.bmp")
	ClosePack(0)
EndIf

Path$ = "C:\ProgramData\PureBasic\Examples\test_delete\"
If OpenPack(0, "C:\ProgramData\PureBasic\Examples\MyCompressedFiles.zip")
	Debug "opened"
	If CreateDirectory(Path$) Or FileSize(Path$) = -2
		Debug "created a folder"
		If ExaminePack(0)
			While NextPackEntry(0)
				Debug "Name: " + PackEntryName(0) + ", Size: " + PackEntrySize(0)
				If UncompressPackFile(0, Path$ + PackEntryName(0), PackEntryName(0)) = -1
					Debug "unsuccessful unpacking of file: " + PackEntryName(0)
				EndIf
			Wend
		EndIf
		ClosePack(0)
		RunProgram(Path$)
	EndIf
EndIf

AddPackFile
Using a tree file structure

Code: Select all

UseZipPacker()

Define Path$ = "C:\ProgramData\PureBasic\Examples\Sources\"
If CreatePack(0, "C:\ProgramData\PureBasic\Examples\MyCompressedFiles.zip")
	AddPackFile(0, Path$ + "Data\world.png", "Data\world.png")
	AddPackFile(0, Path$ + "Data\test.pref", "Data\test.pref")
	AddPackFile(0, Path$ + "Data\CdPlayer.ico", "Data\CdPlayer.ico")
	AddPackFile(0, Path$ + "2DDrawing.pb", "2DDrawing.pb")
	ClosePack(0)
EndIf

Path$ = "C:\ProgramData\PureBasic\Examples\test_delete\"
If OpenPack(0, "C:\ProgramData\PureBasic\Examples\MyCompressedFiles.zip")
	Debug "opened"
	If (CreateDirectory(Path$) And CreateDirectory(Path$ + "Data\")) Or FileSize(Path$ + "Data\") = -2
		Debug "created a folder"
		If ExaminePack(0)
			While NextPackEntry(0)
				Debug "Name: " + PackEntryName(0) + ", Size: " + PackEntrySize(0)
				If UncompressPackFile(0, Path$ + PackEntryName(0), PackEntryName(0)) = -1
					Debug "unsuccessful unpacking of file: " + PackEntryName(0)
				EndIf
			Wend
		EndIf
		ClosePack(0)
		RunProgram(Path$)
	EndIf
EndIf

ChangeSysTrayIcon
The example shows how to create a tray menu, as well as a memory occupancy sensor. You can shorten the example by removing the memory sensor and use it on the AddSysTrayIcon page.

Code: Select all

EnableExplicit

#TrayIcon = 0
#Window = 0
#Menu = 0
#Timer = 0

Global tt = MemoryStatus(#PB_System_TotalPhysical)/16
Global mem


If OpenWindow(#Window, 0, 0, 300, 100, "", #PB_Window_Invisible)
	If CreateImage(0, 16, 16) And StartDrawing(ImageOutput(0))
		Box(0, 0, 16 , 16, $00FFFF)
		StopDrawing()
	EndIf
	If CreatePopupImageMenu(#Menu)
		MenuItem(0, "Exit")
	EndIf
	AddSysTrayIcon(#TrayIcon, WindowID(#Window), ImageID(0))
	AddWindowTimer(#Window, #Timer, 1000)

	;- loop
	Repeat
		Select WaitWindowEvent()
			Case #PB_Event_Timer
				If StartDrawing(ImageOutput(0))
					Box(0, 0, 16 , 16, $00FFFF)
					mem = MemoryStatus(#PB_System_FreePhysical) / tt
					Box(1, mem, 14, 16 - mem, $0000FF)
					StopDrawing()
					ChangeSysTrayIcon(#TrayIcon, ImageID(0))
				EndIf
			Case #PB_Event_SysTray
				Select EventType()
					Case #PB_EventType_RightClick, #PB_EventType_LeftClick
						DisplayPopupMenu(#Menu, WindowID(#Window)) ; show popup menu
				EndSelect
			Case #PB_Event_Menu
				Select EventMenu()
					Case 0 ; Exit
						RemoveSysTrayIcon(#TrayIcon)
						FreeMenu(#Menu)
						CloseWindow(#Window)
						End
				EndSelect
		EndSelect
	ForEver
EndIf

AddSysTrayIcon

Code: Select all

EnableExplicit

#TrayIcon = 0
#Window = 0
#Menu = 0

If OpenWindow(#Window, 0, 0, 300, 100, "", #PB_Window_Invisible)
	If CreatePopupImageMenu(#Menu)
		MenuItem(0, "Exit")
	EndIf
	AddSysTrayIcon(#TrayIcon, WindowID(#Window), LoadImage(0, #PB_Compiler_Home + "Examples\Sources\Data\CdPlayer.ico"))

	Repeat
		Select WaitWindowEvent()
			Case #PB_Event_SysTray
				Select EventType()
					Case #PB_EventType_RightClick, #PB_EventType_LeftClick
						DisplayPopupMenu(#Menu, WindowID(#Window)) ; show popup menu
				EndSelect
			Case #PB_Event_Menu
				Select EventMenu()
					Case 0 ; Exit
						RemoveSysTrayIcon(#TrayIcon)
						FreeMenu(#Menu)
						CloseWindow(#Window)
						End
				EndSelect
		EndSelect
	ForEver
EndIf

[Andre]

Examples added for:
- ScintillaSendMessage
- Chr
- FindString

Mostly in a bit simplified / adapted form. More to follow...

Thanks, AZJIO

There are many examples in the French help file that are not in the English help. For example, look at the "FileSystem" section, in English there is almost no example there, but in French there are examples on every page.

This is something @mesa should look for... because the English docs are the 'leading' documentation as written here: viewtopic.php?t=79835&start=6

[Andre]

Examples added for:
- WritePreferenceInteger
- WritePreferenceString
Both in a bit adapted form + together with notes/links from other Preference commands.

Example adapted for:
- ExaminePreferenceKeys (from MessageRequester to Debug, as 4x the requester is really a bit much)
(example for ExaminePreferenceGroups not adapted, as the use of MessageRequester 2-times seems OK for me)

More to follow...

Thanks, AZJIO

[Andre]

Examples added to Packer library docs:
- UncompressPackFile
- AddPackFile

Both in a slightly modified and commented form. Thanks, AZJIO!

[Kuron]

Thank you AZJIO & Andre!

[AZJIO]

AddKeyboardShortcut
The example feature shows that you can create hotkeys for missing menu items. This is not stated on the description page.

Code: Select all

#Window = 0
Enumeration Menu
	#Menu
	#PopupMenu
EndEnumeration
Enumeration Menu_items
	#mOpen
	#mCopy
	#mDummy1
	#mDummy2
EndEnumeration

If OpenWindow(#Window, 200, 200, 200, 100, "Press Ctrl+D")
	If CreateMenu(#Menu, WindowID(#Window))
		MenuTitle("File")
		MenuItem(#mOpen, "Open" + #TAB$ + "Ctrl+O")
	EndIf
	If CreatePopupMenu(#PopupMenu)
		MenuItem(#mCopy, "Copy" + #TAB$ + "Ctrl+Shift+C")
	EndIf
	AddKeyboardShortcut(#Window, #PB_Shortcut_Control | #PB_Shortcut_O, #mOpen)
	AddKeyboardShortcut(#Window, #PB_Shortcut_Control | #PB_Shortcut_Shift | #PB_Shortcut_C, #mCopy)
	AddKeyboardShortcut(#Window, #PB_Shortcut_Control | #PB_Shortcut_D, #mDummy1)
	AddKeyboardShortcut(#Window, #PB_Shortcut_Control | #PB_Shortcut_F, #mDummy2)
	Repeat
		Select WaitWindowEvent()
			Case #PB_Event_RightClick
				DisplayPopupMenu(#PopupMenu, WindowID(#Window))
			Case #PB_Event_Menu
				Select EventMenu()
					Case #mOpen : Debug "Open"
					Case #mCopy : Debug "Copy"
					Case #mDummy1 : Debug "Dummy1"
					Case #mDummy2 : Debug "Dummy2"
				EndSelect
			Case #PB_Event_CloseWindow
				CloseWindow(#Window)
				End
		EndSelect
	ForEver
EndIf