[Seen]Better docs for default values (#PB_Default)

Found an issue in the documentation ? Please report it here !

Moderator: Documentation Editors

User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

[Seen]Better docs for default values (#PB_Default)

Post by luis »

Every time a PB command has one or more optional parameters, when it's possible/applicable would be nice if it were mentioned what is the default value used if the param is not specified.

An example:

Code: Select all

Result = CreateFile(#File, Filename$ [, Flags])

Flags (optional) 
  It can be a combination (using the '| operand) of the following values: 
  #PB_File_SharedRead : the opened file can be read by another process (Windows only).
  #PB_File_SharedWrite: the opened file can be write by another process (Windows only).
  #PB_File_NoBuffering: the internal PureBasic file buffering system will be disabled for this file. 
If I want to create a file with buffering or no buffering depending on a variable to be passed in place of [Flags], what values must it have ?

#PB_File_NoBuffering if I don't want buffering, but if I want it ? 0 ? -1 ? #PB_Default, #PB_Ignore ? Something else ?

The alternative is to write an IF/ELSE/ENDIF with two calls to CreateFile(), one with #PB_File_NoBuffering and one without the optional param, but this should be not required.

Another example: suppose I want to redefine a PB command through a macro with the same name, maybe I just do something in addition to the original command and then I need to call it anyway. Maybe I'm tracing the command execution, or I'm doing something like this -> NoLeak.

If the command has optional params, and I don't know their defaults, how can I write the macro ?

Code: Select all

Result = CatchImage(#Image, *MemoryAddress [, Size])
[Size] is optional, and I want to wrap the command in a macro. What must be the default value for [Size] if not specified when calling the macro ?


Same type of problem selected at random from the helpfile:

Code: Select all

Result = CRC32Fingerprint(*Buffer, Size [, InitialValue]) 
Result$ = SHA1FileFingerprint(Filename$ [, Offset [, Length]])
Filename$ = GetFilePart(FullPathName$ [, Mode])
UnbindEvent(Event, @Callback() [, Window [, Object [, EventType]]]) 
DrawAlphaImage(ImageID, x, y [, ConstAlpha])
...
Maybe a good thing would be to make possible to pass #PB_Default explicitly and in that case the appropriate default values would be used like if the params were missing. Having that and also knowing what the actual value is would be the best.

CreateImage() is one of the commands which gives this info:

Code: Select all

Result = CreateImage(#Image, Width, Height [, Depth [, BackColor]])

Depth (optional) The color depth for the new image. Valid values can be: 24 and 32. The default is 24-bit if no depth is specified.

BackColor (optional) The back RGB() color used when the image is created. This color can be set to #PB_Image_Transparent to create an image with the alpha channel set to full transparent. This only has an effect on 32-bit images. The default backcolor is black if not specified.  
Some others say something but still not enough:

Code: Select all

Box(x, y, Width, Height [, Color])

Color (optional) The color to be used for the box. If this parameter is not specified, the default color set with FrontColor() will be used. This color can be in RGB or RGBA format. 
But what is the color if FrontColor() is not used ? Clearly an actual color is in any case used to draw.
I can write a program (or many, for different OSes) to hopefully discover that but it should be in the docs, probably in the help for FrontColor().

I shouldn't have to try to guess, I should just have to read the docs.

I don't know if this is more appropriate here or in Feature Requests, in case please move it.
Last edited by luis on Fri Apr 17, 2015 1:40 pm, edited 3 times in total.
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
Thunder93
Addict
Addict
Posts: 1788
Joined: Tue Mar 21, 2006 12:31 am
Location: Canada

Re: Better docs for default values (and/or enable #PB_Defaul

Post by Thunder93 »

I personally think its pretty clear. For instances regarding CreateFile(). None of those flags are used by default. #PB_File_NoBuffering passes number four to have the internal buffering system disabled.

#PB_Default, #PB_Ignore aren't always supported. If It were it would have likely been stated in the document for under this PB command .. like so as shown throughout the PB help document.

If you want to redefine a PB command through a macro, for instances as with CreateFile(). Why not simply use CreateFile(..., flags.l = 0)

I know, you know all this. Lay off the bottle! :wink: :mrgreen:
ʽʽSuccess is almost totally dependent upon drive and persistence. The extra energy required to make another effort or try another approach is the secret of winning.ʾʾ --Dennis Waitley
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

Re: Better docs for default values (and/or enable #PB_Defaul

Post by luis »

Thunder93 wrote:... regarding CreateFile(). None of those flags are used by default. #PB_File_NoBuffering passes number four to have the internal buffering system disabled.
Uh ? That's clear yes. I'm not asking which of those possible documented values is used as default if the optional param is not specified.
I'm saying I would like to know what value I can pass to [Flags] to simulate not passing a parameter.
I wrote an example toclarify that, the IF/THEN/ELSE part in the post above.
It's not specific to Createfile(), you may want to do the same with many other commands too.

Thunder93 wrote: If you want to redefine a PB command through a macro, for instances as with CreateFile(). Why not simply use CreateFile(..., flags.l = 0)
Because I don't know what will happen inside the CreateFile() command if I pass 0 for the [Flags] parameter ?
If I want to create a file with buffering or no buffering depending on a variable to be passed in place of [Flags], what values must it have ?
#PB_File_NoBuffering if I don't want buffering, but if I want it ? 0 ? -1 ? #PB_Default, #PB_Ignore ? Something else ?
Why should I choose an arbitrary value, not specified in the expected list of params ?
That's why I wrote extending the use of #PB_Default for this and/or knowing the actual value may be an idea.
Last edited by luis on Fri Apr 17, 2015 1:09 am, edited 1 time in total.
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
Thunder93
Addict
Addict
Posts: 1788
Joined: Tue Mar 21, 2006 12:31 am
Location: Canada

Re: Better docs for default values (and/or enable #PB_Defaul

Post by Thunder93 »

When I was doing up the DPI-Scaling Demonstration code (http://www.purebasic.fr/english/viewtop ... 99#p463799), for on the topic - How to handle Windows UI scaling? ..I had the same concerns when working on the redefining PB commands through macros.

OpenWindow() for instance: #PB_Window_SystemMenu is stated as default flag, so really I don't need to specify a flag to have this. What should I return 0, or -1 for my macro? Returning -1 seems to have the gadgetlist not become created. 0 is purely clean state, nothing applied. Therefore I need to have my OpenWindow() macro look like the following;

Code: Select all

Macro OpenWindow(WindowID, x, y, Width, Height, Title, Flags = #PB_Window_SystemMenu)
  _OpenWindow(WindowID, Dx(x), Dy(y), Dx(Width), Dy(Height), Title, Flags)
EndMacro

EditorGadget(), nothing listed stated to be the default flag. Return 0? or return -1? Returning again -1 causes problems, this time using -1 doesn't have the EditorGadget() created.

So with PB commands like EditorGadget() or CreateFile(), I would specify flags = 0

.. for PB commands like OpenWindow(), use Flags = #[Default-flag]
ʽʽSuccess is almost totally dependent upon drive and persistence. The extra energy required to make another effort or try another approach is the secret of winning.ʾʾ --Dennis Waitley
User avatar
luis
Addict
Addict
Posts: 3876
Joined: Wed Aug 31, 2005 11:09 pm
Location: Italy

Re: Better docs for default values (and/or enable #PB_Defaul

Post by luis »

So with PB commands like EditorGadget() or CreateFile(), I would specify flags = 0
I would like instead to specify what's documented as the correct value, not trying random values to see what seems to work, that"s why I"m asking for the documentation to be extended with this, and maybe to extend the use of #PB_Default.

That's the whole reason behind the first post.
.. for PB commands like OpenWindow(), use Flags = #[Default-flag]
Obviously, since the default value it's documented.
"Have you tried turning it off and on again ?"
A little PureBasic review
User avatar
TI-994A
Addict
Addict
Posts: 2512
Joined: Sat Feb 19, 2011 3:47 am
Location: Singapore
Contact:

Re: Better docs for default values (and/or enable #PB_Defaul

Post by TI-994A »

luis wrote:Every time a PB command has one or more optional parameters, when it's possible/applicable would be nice if it were mentioned what is the default value used if the param is not specified.
Yes, it would be nice, although quite unnecessary.

The examples you cited seem to be quite intuitive as explained in the manual.
GetFilePart(): default Mode would be with extension
CRC32Fingerprint(): default InitialValue would be the start of the buffer
UnbindEvent(): corresponds to a BindEvent() - and accordingly to the bound Window, Object, and EventType
SHA1FileFingerprint(): default Offset would be the start of the file, and the default Length would be the length of the file from the desired offset
As for the drawing functions, it's probably assumed that the colors would be set by the developer, being drawing functions after all. It could also be assumed that there is no default front color unless the FrontColor() function is specifically used to set one:
PureBasic Manual: FrontColor() wrote:Set the default color for graphic functions and text display.
Nevertheless, when function defaults are set by leaving optional flags blank, perhaps that's the way they're meant to work. There may very well be some undocumented default values for them, but why add verbosity.

The syntax and structure of these functions should not have to conform to your macro requirements. If you'd like to modify them, then you'd have to work around them - not the other way around.

Just some thoughts. :wink:
Texas Instruments TI-99/4A Home Computer: the first home computer with a 16bit processor, crammed into an 8bit architecture. Great hardware - Poor design - Wonderful BASIC engine. And it could talk too! Please visit my YouTube Channel :D
c4s
Addict
Addict
Posts: 1981
Joined: Thu Nov 01, 2007 5:37 pm
Location: Germany

Re: Better docs for default values (and/or enable #PB_Defaul

Post by c4s »

+1 for luis' original "feature request".
If any of you native English speakers have any suggestions for the above text, please let me know (via PM). Thanks!
User avatar
Andre
PureBasic Team
PureBasic Team
Posts: 2056
Joined: Fri Apr 25, 2003 6:14 pm
Location: Germany (Saxony, Deutscheinsiedel)
Contact:

Re: [Seen]Better docs for default values (#PB_Default)

Post by Andre »

This is something for Fred / freak, as not related to a single command and internal knowledge is needed to fulfil this request.
Bye,
...André
(PureBasicTeam::Docs & Support - PureArea.net | Order:: PureBasic | PureVisionXP)
Post Reply