From f7abc0e1fda6f964b5367072c71b99b3fc3b8225 Mon Sep 17 00:00:00 2001 From: Fellippe Heitor Date: Tue, 10 Oct 2017 11:55:21 -0300 Subject: [PATCH] Update help files. --- internal/help/$CHECKING.txt | 35 +- internal/help/$CONSOLE.txt | 16 +- internal/help/$DYNAMIC.txt | 18 +- internal/help/$ELSE.txt | 36 +- internal/help/$ELSEIF.txt | 44 +- internal/help/$END_IF.txt | 23 +- internal/help/$IF.txt | 45 +- internal/help/$INCLUDE.txt | 44 +- internal/help/$LET.txt | 41 +- internal/help/$RESIZE.txt | 105 ++- internal/help/$SCREENHIDE.txt | 14 +- internal/help/$SCREENSHOW.txt | 15 +- internal/help/$VIRTUALKEYBOARD.txt | 13 +- internal/help/ABS.txt | 13 +- internal/help/ACCESS.txt | 18 +- internal/help/ALIAS.txt | 22 +- internal/help/AND.txt | 30 +- internal/help/AND_(boolean).txt | 11 +- internal/help/ANY.txt | 10 +- internal/help/APPEND.txt | 10 +- internal/help/AS.txt | 48 +- internal/help/ASC.txt | 32 +- internal/help/ASC_(statement).txt | 16 +- internal/help/ATN.txt | 16 +- internal/help/Apostrophe.txt | 22 +- internal/help/BEEP.txt | 32 +- internal/help/BINARY.txt | 25 +- internal/help/BLOAD.txt | 24 +- internal/help/BSAVE.txt | 68 +- internal/help/BYVAL.txt | 31 +- internal/help/CALL.txt | 30 +- internal/help/CALLS.txt | 26 +- internal/help/CALL_ABSOLUTE.txt | 205 +----- internal/help/CASE.txt | 53 +- internal/help/CASE_ELSE.txt | 16 +- internal/help/CASE_IS.txt | 7 +- internal/help/CDBL.txt | 9 +- internal/help/CDECL.txt | 16 +- internal/help/CHAIN.txt | 35 +- internal/help/CHDIR.txt | 24 +- internal/help/CHR$.txt | 22 +- internal/help/CINT.txt | 24 +- internal/help/CIRCLE.txt | 103 +-- internal/help/CLEAR.txt | 20 +- internal/help/CLNG.txt | 13 +- internal/help/CLOSE.txt | 18 +- internal/help/CLS.txt | 33 +- internal/help/COLOR.txt | 134 ++-- internal/help/COMMAND$.txt | 25 +- internal/help/COMMON.txt | 26 +- internal/help/CONST.txt | 35 +- internal/help/COS.txt | 14 +- internal/help/CSNG.txt | 11 +- internal/help/CSRLIN.txt | 12 +- internal/help/CVD.txt | 45 +- internal/help/CVDMBF.txt | 33 +- internal/help/CVI.txt | 33 +- internal/help/CVL.txt | 28 +- internal/help/CVS.txt | 46 +- internal/help/CVSMBF.txt | 33 +- internal/help/DATA.txt | 30 +- internal/help/DATE$.txt | 21 +- internal/help/DATE$_(statement).txt | 21 +- internal/help/DECLARE.txt | 5 + .../help/DECLARE_(non-BASIC_statement).txt | 8 +- internal/help/DECLARE_DYNAMIC_LIBRARY.txt | 37 +- internal/help/DECLARE_LIBRARY.txt | 50 +- internal/help/DEFDBL.txt | 34 +- internal/help/DEFINT.txt | 46 +- internal/help/DEFLNG.txt | 38 +- internal/help/DEFSNG.txt | 40 +- internal/help/DEFSTR.txt | 36 +- internal/help/DEF_FN.txt | 27 +- internal/help/DEF_SEG.txt | 19 +- internal/help/DIM.txt | 55 +- internal/help/DIR$.txt | 89 +-- internal/help/DO...LOOP.txt | 35 +- internal/help/DOUBLE.txt | 17 +- internal/help/DRAW.txt | 65 +- internal/help/ELSE.txt | 30 +- internal/help/ELSEIF.txt | 31 +- internal/help/END.txt | 34 +- internal/help/ENVIRON$.txt | 52 +- internal/help/ENVIRON.txt | 19 +- internal/help/EOF.txt | 21 +- internal/help/EQV.txt | 8 +- internal/help/ERASE.txt | 18 +- internal/help/ERDEV$.txt | 12 +- internal/help/ERDEV.txt | 14 +- internal/help/ERL.txt | 7 +- internal/help/ERR.txt | 16 +- internal/help/ERROR.txt | 10 +- internal/help/EXIT.txt | 22 +- internal/help/EXP.txt | 18 +- internal/help/FIELD.txt | 13 +- internal/help/FILEATTR.txt | 14 +- internal/help/FILES.txt | 54 +- internal/help/FIX.txt | 15 +- internal/help/FOR...NEXT.txt | 50 +- internal/help/FOR_(file_statement).txt | 18 +- internal/help/FRE.txt | 30 +- internal/help/FREEFILE.txt | 17 +- internal/help/FUNCTION.txt | 70 +- internal/help/GET.txt | 26 +- internal/help/GET_(TCP%2FIP_statement).txt | 36 +- internal/help/GET_(graphics_statement).txt | 41 +- internal/help/GOSUB.txt | 26 +- internal/help/GOTO.txt | 23 +- internal/help/HEX$.txt | 17 +- internal/help/IF...THEN.txt | 63 +- internal/help/IMP.txt | 12 +- internal/help/INKEY$.txt | 47 +- internal/help/INP.txt | 15 +- internal/help/INPUT$.txt | 34 +- internal/help/INPUT.txt | 58 +- internal/help/INPUT_(TCP%2FIP_statement).txt | 36 +- internal/help/INPUT_(file_mode).txt | 29 +- internal/help/INPUT_(file_statement).txt | 28 +- internal/help/INSTR.txt | 33 +- internal/help/INT.txt | 15 +- internal/help/INTEGER.txt | 23 +- internal/help/INTERRUPT.txt | 33 +- internal/help/INTERRUPTX.txt | 42 +- internal/help/IOCTL$.txt | 16 +- internal/help/IOCTL.txt | 19 +- internal/help/KEY(n).txt | 13 +- internal/help/KEY_LIST.txt | 22 +- internal/help/KEY_n.txt | 27 +- internal/help/KILL.txt | 26 +- .../help/Keyword_Reference_-_Alphabetical.txt | 139 ++-- .../help/Keyword_Reference_-_By_usage.txt | 14 +- internal/help/LBOUND.txt | 12 +- internal/help/LCASE$.txt | 7 +- internal/help/LEFT$.txt | 20 +- internal/help/LEN.txt | 19 +- internal/help/LET.txt | 12 +- internal/help/LINE.txt | 69 +- internal/help/LINE_INPUT.txt | 30 +- internal/help/LINE_INPUT_(file_statement).txt | 29 +- internal/help/LOC.txt | 16 +- internal/help/LOCATE.txt | 24 +- internal/help/LOCK.txt | 23 +- internal/help/LOF.txt | 17 +- internal/help/LOG.txt | 13 +- internal/help/LONG.txt | 18 +- internal/help/LPOS.txt | 5 +- internal/help/LPRINT.txt | 12 +- internal/help/LPRINT_USING.txt | 16 +- internal/help/LSET.txt | 13 +- internal/help/LTRIM$.txt | 13 +- internal/help/MID$.txt | 34 +- internal/help/Mathematical_Operations.txt | 40 +- internal/help/NEXT.txt | 34 +- internal/help/ON_COM(n).txt | 7 +- internal/help/ON_PEN.txt | 8 +- internal/help/ON_PLAY(n).txt | 8 +- internal/help/ON_UEVENT.txt | 8 +- internal/help/OPEN.txt | 179 ++--- internal/help/OR_(boolean).txt | 1 + internal/help/OUT.txt | 12 +- internal/help/PAINT.txt | 37 +- internal/help/PCOPY.txt | 2 +- internal/help/PEN.txt | 8 +- internal/help/PEN_(statement).txt | 8 +- internal/help/PLAY(n).txt | 8 +- internal/help/PRESET.txt | 8 +- internal/help/PRINT.txt | 4 +- internal/help/PRINT_(TCP%2FIP_statement).txt | 4 + internal/help/PSET.txt | 6 +- internal/help/QB64_FAQ.txt | 690 +++++++----------- internal/help/READ.txt | 25 +- internal/help/RESUME.txt | 14 +- internal/help/RUN.txt | 11 +- internal/help/SCREEN.txt | 2 +- internal/help/SELECT_CASE.txt | 60 +- internal/help/SETMEM.txt | 8 +- internal/help/SHELL.txt | 43 +- internal/help/SIGNAL.txt | 8 +- internal/help/SIN.txt | 3 +- internal/help/SYSTEM.txt | 10 +- internal/help/TIMER_(statement).txt | 3 +- internal/help/TROFF.txt | 8 +- internal/help/TRON.txt | 8 +- internal/help/UCASE$.txt | 9 +- internal/help/WHILE...WEND.txt | 1 + internal/help/WIDTH.txt | 13 +- internal/help/XOR.txt | 2 +- internal/help/_ACOS.txt | 17 +- internal/help/_ACOSH.txt | 14 +- internal/help/_ALPHA.txt | 11 +- internal/help/_ALPHA32.txt | 16 +- internal/help/_ASIN.txt | 22 +- internal/help/_ASINH.txt | 13 +- internal/help/_ATAN2.txt | 11 +- internal/help/_ATANH.txt | 13 +- internal/help/_AUTODISPLAY.txt | 12 +- internal/help/_AXIS.txt | 9 +- internal/help/_BACKGROUNDCOLOR.txt | 21 +- internal/help/_BIT.txt | 19 +- internal/help/_BLEND.txt | 18 +- internal/help/_BLEND_(function).txt | 10 +- internal/help/_BLUE.txt | 8 +- internal/help/_BLUE32.txt | 16 +- internal/help/_BUTTON.txt | 12 +- internal/help/_BUTTONCHANGE.txt | 12 +- internal/help/_BYTE.txt | 10 +- internal/help/_CEIL.txt | 13 +- internal/help/_CLEARCOLOR.txt | 23 +- internal/help/_CLEARCOLOR_(function).txt | 6 +- internal/help/_CLIP.txt | 7 +- internal/help/_CLIPBOARD$.txt | 4 +- internal/help/_CLIPBOARD$_(statement).txt | 12 +- internal/help/_COMMANDCOUNT.txt | 5 +- internal/help/_CONNECTED.txt | 22 +- internal/help/_CONNECTIONADDRESS$.txt | 47 +- internal/help/_CONSOLE.txt | 25 +- internal/help/_CONSOLETITLE.txt | 8 +- internal/help/_CONTROLCHR.txt | 20 +- internal/help/_CONTROLCHR_(function).txt | 8 +- internal/help/_COPYIMAGE.txt | 23 +- internal/help/_COPYPALETTE.txt | 15 +- internal/help/_CV.txt | 21 +- internal/help/_CWD$.txt | 10 +- internal/help/_D2G.txt | 10 +- internal/help/_D2R.txt | 10 +- internal/help/_DEFAULTCOLOR.txt | 7 +- internal/help/_DEFINE.txt | 21 +- internal/help/_DELAY.txt | 6 +- internal/help/_DEPTHBUFFER.txt | 13 +- internal/help/_DESKTOPHEIGHT.txt | 13 +- internal/help/_DESKTOPWIDTH.txt | 13 +- internal/help/_DEST.txt | 5 +- internal/help/_DEST_(function).txt | 8 +- internal/help/_DEVICE$.txt | 11 +- internal/help/_DEVICEINPUT.txt | 18 +- internal/help/_DEVICES.txt | 11 +- internal/help/_DIREXISTS.txt | 21 +- internal/help/_DISPLAY.txt | 20 +- internal/help/_DISPLAYORDER.txt | 14 +- internal/help/_DISPLAY_(function).txt | 17 +- internal/help/_DONTBLEND.txt | 13 +- internal/help/_DONTWAIT.txt | 9 +- internal/help/_ERRORLINE.txt | 10 +- internal/help/_EXIT_(function).txt | 25 +- internal/help/_FILEEXISTS.txt | 22 +- internal/help/_FLOAT.txt | 14 +- internal/help/_FONT.txt | 23 +- internal/help/_FONTHEIGHT.txt | 10 +- internal/help/_FONTWIDTH.txt | 11 +- internal/help/_FONT_(function).txt | 9 +- internal/help/_FREEFONT.txt | 19 +- internal/help/_FREEIMAGE.txt | 19 +- internal/help/_FREETIMER.txt | 6 +- internal/help/_FULLSCREEN.txt | 44 +- internal/help/_FULLSCREEN_(function).txt | 22 +- internal/help/_G2D.txt | 11 +- internal/help/_G2R.txt | 11 +- internal/help/_GREEN.txt | 10 +- internal/help/_GREEN32.txt | 8 +- internal/help/_HIDE.txt | 15 +- internal/help/_ICON.txt | 36 +- internal/help/_INTEGER64.txt | 12 +- internal/help/_KEYCLEAR.txt | 57 +- internal/help/_KEYHIT.txt | 22 +- internal/help/_LASTAXIS.txt | 10 +- internal/help/_LASTBUTTON.txt | 13 +- internal/help/_LASTWHEEL.txt | 13 +- internal/help/_LIMIT.txt | 13 +- internal/help/_LOADFONT.txt | 47 +- internal/help/_LOADIMAGE.txt | 35 +- internal/help/_MAPTRIANGLE.txt | 39 +- internal/help/_MAPUNICODE.txt | 16 +- internal/help/_MAPUNICODE_(function).txt | 20 +- internal/help/_MEM.txt | 108 ++- internal/help/_MEMCOPY.txt | 21 +- internal/help/_MEMELEMENT.txt | 34 +- internal/help/_MEMEXISTS.txt | 14 +- internal/help/_MEMFILL.txt | 21 +- internal/help/_MEMFREE.txt | 14 +- internal/help/_MEMGET.txt | 21 +- internal/help/_MEMGET_(function).txt | 25 +- internal/help/_MEMIMAGE.txt | 17 +- internal/help/_MEMNEW.txt | 25 +- internal/help/_MEMPUT.txt | 23 +- internal/help/_MEM_(function).txt | 25 +- internal/help/_MK$.txt | 15 +- internal/help/_MOUSEBUTTON.txt | 23 +- internal/help/_MOUSEHIDE.txt | 11 +- internal/help/_MOUSEINPUT.txt | 11 +- internal/help/_MOUSEMOVE.txt | 21 +- internal/help/_MOUSEMOVEMENTX.txt | 10 +- internal/help/_MOUSEMOVEMENTY.txt | 11 +- internal/help/_MOUSEPIPEOPEN.txt | 17 +- internal/help/_MOUSESHOW.txt | 37 +- internal/help/_MOUSEWHEEL.txt | 18 +- internal/help/_MOUSEX.txt | 24 +- internal/help/_MOUSEY.txt | 23 +- internal/help/_NEWIMAGE.txt | 42 +- internal/help/_OFFSET.txt | 15 +- internal/help/_OFFSET_(function).txt | 17 +- internal/help/_OPENCLIENT.txt | 8 +- internal/help/_OPENCONNECTION.txt | 18 +- internal/help/_OPENHOST.txt | 14 +- internal/help/_OS$.txt | 18 +- internal/help/_PALETTECOLOR.txt | 19 +- internal/help/_PALETTECOLOR_(function).txt | 14 +- internal/help/_PI.txt | 11 +- internal/help/_PIXELSIZE.txt | 19 +- internal/help/_PRESERVE.txt | 23 +- internal/help/_PRINTIMAGE.txt | 15 +- internal/help/_PRINTMODE.txt | 21 +- internal/help/_PRINTMODE_(function).txt | 15 +- internal/help/_PRINTSTRING.txt | 40 +- internal/help/_PRINTWIDTH.txt | 17 +- internal/help/_PUTIMAGE.txt | 74 +- internal/help/_R2D.txt | 10 +- internal/help/_R2G.txt | 10 +- internal/help/_RED.txt | 10 +- internal/help/_RED32.txt | 10 +- internal/help/_RESIZE.txt | 8 +- internal/help/_RESIZEHEIGHT.txt | 51 +- internal/help/_RESIZEWIDTH.txt | 51 +- internal/help/_RESIZE_(function).txt | 47 +- internal/help/_RGB.txt | 23 +- internal/help/_RGB32.txt | 21 +- internal/help/_RGBA.txt | 21 +- internal/help/_RGBA32.txt | 28 +- internal/help/_ROUND.txt | 6 +- internal/help/_SCREENCLICK.txt | 7 +- internal/help/_SCREENEXISTS.txt | 10 +- internal/help/_SCREENICON.txt | 13 +- internal/help/_SCREENICON_(function).txt | 6 +- internal/help/_SCREENIMAGE.txt | 36 +- internal/help/_SCREENMOVE.txt | 57 +- internal/help/_SCREENPRINT.txt | 18 +- internal/help/_SCREENSHOW.txt | 8 +- internal/help/_SCREENX.txt | 14 +- internal/help/_SCREENY.txt | 12 +- internal/help/_SETALPHA.txt | 29 +- internal/help/_SHELLHIDE.txt | 16 +- internal/help/_SNDBAL.txt | 99 ++- internal/help/_SNDCLOSE.txt | 17 +- internal/help/_SNDCOPY.txt | 25 +- internal/help/_SNDGETPOS.txt | 23 +- internal/help/_SNDLEN.txt | 28 +- internal/help/_SNDLIMIT.txt | 12 +- internal/help/_SNDLOOP.txt | 8 +- internal/help/_SNDOPEN.txt | 101 ++- internal/help/_SNDOPENRAW.txt | 8 +- internal/help/_SNDPAUSE.txt | 28 +- internal/help/_SNDPAUSED.txt | 20 +- internal/help/_SNDPLAY.txt | 5 +- internal/help/_SNDPLAYCOPY.txt | 39 +- internal/help/_SNDPLAYFILE.txt | 24 +- internal/help/_SNDPLAYING.txt | 6 +- internal/help/_SNDRATE.txt | 15 +- internal/help/_SNDRAW.txt | 35 +- internal/help/_SNDRAWDONE.txt | 19 +- internal/help/_SNDRAWLEN.txt | 20 +- internal/help/_SNDSETPOS.txt | 30 +- internal/help/_SNDSTOP.txt | 7 +- internal/help/_SNDVOL.txt | 27 +- internal/help/_SOURCE.txt | 13 +- internal/help/_SOURCE_(function).txt | 11 +- internal/help/_STARTDIR$.txt | 12 +- internal/help/_STRCMP.txt | 11 +- internal/help/_STRICMP.txt | 8 +- internal/help/_TITLE.txt | 18 +- internal/help/_UNSIGNED.txt | 31 +- internal/help/_WHEEL.txt | 12 +- internal/help/_WIDTH_(function).txt | 18 +- internal/help/links.bin | 18 +- 372 files changed, 4863 insertions(+), 4658 deletions(-) diff --git a/internal/help/$CHECKING.txt b/internal/help/$CHECKING.txt index 682a35dd7..f764b222e 100644 --- a/internal/help/$CHECKING.txt +++ b/internal/help/$CHECKING.txt @@ -1,27 +1,22 @@ -The $CHECKING metacommand turns C++ event checking ON or OFF. +The [[$CHECKING]] metacommand turns C++ event checking ON or OFF. -''Syntax:'' $CHECKING:OFF +{{PageSyntax}} +: [[$CHECKING]]:{ON|OFF} + +{{PageDescription}} +* The Metacommand does '''not''' require a comment or REM before it. There is no space after the colon. +* The OFF action turns event checking off and should '''only be used when running stable, errorless code.''' +* The default [[$CHECKING]]:ON action is only required when checking has been turned OFF previously. +* When [[$CHECKING]]:OFF is used, all error code and the reporting code is removed from the EXE program. +* '''Warning: Turning OFF error checking could create a General Protection Fault. + +===Details=== +* After every QB64 command is translated to C++, the compiler adds special code sections to check for [[ON TIMER (n)]] events and errors that may have occured in the last function call. Disabling error checking with the [[$CHECKING]]:OFF directive prevents the compiler from adding the extra code sections. +* Setting [[$CHECKING]]:OFF is only designed for 100% stable, error-less sections of code, where every CPU cycle saved counts, such as in a software 3D texture mapper, for example. -* The Metacommand does '''NOT''' require a comment or REM before it! There is no space after the colon. -* The OFF action turns event checking off and should '''ONLY be used when running stable, errorless code!''' -* The default $CHECKING:ON action is only required when checking has been turned OFF previously. -* When $CHECKING:OFF is used, all error code and the reporting code is removed from the EXE program. -* '''WARNING! Turning OFF error checking could create a General Protection Fault!''' - - -''Explanation:'' After every QB64 command a C++ check as follows is performed: If (qbevent){... - -: Using [[ON TIMER (n)]] merely sets qbevent when appropriate, causing little/no difference to the speed your program runs. Unless you are using the QB64 direct meta-command to avoid this: - -:::$CHECKING:OFF - -:But turning checking off is only designed for 100% stable, error-less sections of code, where every CPU cycle saved counts. Such as in a software 3D texture mapper. - - -''See also:'' - +{{PageSeeAlso}} * [[ON TIMER(n)]] * [[ON ERROR]] * [[Metacommand]] diff --git a/internal/help/$CONSOLE.txt b/internal/help/$CONSOLE.txt index c5063e2f6..8e4ba7023 100644 --- a/internal/help/$CONSOLE.txt +++ b/internal/help/$CONSOLE.txt @@ -1,21 +1,22 @@ -The '''$CONSOLE''' [[Metacommand]] creates a console window that can be used throughout a QB64 program module. +The [[$CONSOLE]] [[Metacommand]] creates a console window that can be used throughout a QB64 program module. {{PageSyntax}} -::: '''$CONSOLE''' {ON|OFF|ONLY} +: [[$CONSOLE]][:ONLY] -* [[_CONSOLE]] '''ON''' or '''OFF''' may be used to show or hide the console window. OFF can only be used after ON. -* The '''ONLY''' option can be used when only a console window is desired without a program window. +* [[_CONSOLE]] '''ON''' or '''OFF''' may be used to show or hide the console window at run time. +* The ''':ONLY''' option can be used when only a console window is desired without a program window. * [[_DEST]] [[_CONSOLE]] may be used to send screen output to the console window. * [[_SCREENHIDE]] and [[_SCREENSHOW]] can be used to hide or show the main program window. * [[_DELAY]] or [[SLEEP]] can be used to allow the console window to be set in front of the main program window. -* '''QB64 [[Metacommand]]s require that commenting or [[REM]] NOT be used anywhere on the Metacommand code line!''' -* Change the title of the [[$CONSOLE]] windows created using: [[SHELL]] "title consoletitle" +* '''QB64 [[Metacommand]]s are not commented out with ' or REM, differently from Qbasic metacommands''' +* Change the title of the [[$CONSOLE]] windows created using [[_CONSOLETITLE]] * '''Note:''' Text can be copied partially or totally from console screens in Windows by highlighting and using the title bar menu. :: To copy console text output, right click the title bar and select ''Edit'' for ''Mark'' to highlight and repeat to ''Copy'' +{{PageExamples}} ''Example 1:'' Hiding and displaying a console window. Use [[_DELAY]] to place console in front of main program window. {{CodeStart}} '' '' {{Cl|$CONSOLE}} @@ -65,10 +66,11 @@ Max hex _INTEGER64 = FFFFFFFFFFFFFFFF with 16 digits =-1 :''Copied text:'' The above text was copied after ''Select All'' was selected and the smaller area was re-highlighted with the mouse. -''See also:'' +{{PageSeeAlso}} * [[_CONSOLE]] * [[$SCREENHIDE]], [[$SCREENSHOW]] (QB64 [[Metacommand]]s) * [[_SCREENHIDE]], [[_SCREENSHOW]] +* [[C_Libraries#Console_Window|C Console Library]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/$DYNAMIC.txt b/internal/help/$DYNAMIC.txt index ed4e9b6b2..ba3b2256e 100644 --- a/internal/help/$DYNAMIC.txt +++ b/internal/help/$DYNAMIC.txt @@ -1,20 +1,20 @@ -The '''$DYNAMIC''' Metacommand allows the creation of dynamic(changeable) array sizes. - +The [[$DYNAMIC]] [[Metacommand|metacommand]] allows the creation of dynamic (changeable) arrays. {{PageSyntax}} -::REM $DYNAMIC +:{[[REM]] | ' } [[$DYNAMIC]] -* Qbasic [[Metacommand]]s require a REM or apostrophy (') before them and are always placed at the start of the main module. +{{PageDescription}} +* QBasic [[Metacommand|metacommands]] require [[REM]] or [[Apostrophe|apostrophe]] (') before them and are always placed at the start of the main module. * Dynamic arrays can be resized using [[REDIM]]. The array's type cannot be changed. -* All data in the array will be lost when [[REDIM]]ensioned except when [[_PRESERVE]] is used in QB64 only. +* All data in the array will be lost when [[REDIM]]ensioned except when [[_PRESERVE]] is used. * [[REDIM]] [[_PRESERVE]] can preserve and may move the previous array data when the array boundaries change. -* [[_PRESERVE]] allows the [[UBOUND|upper]] and [[LBOUND|lower]] boundaries of an array to be changed. The number of dimensions cannot change! -* Dynamic arrays can also be resized by the program user's input if desired. -* $DYNAMIC arrays MUST be [[REDIM]]ensioned if [[ERASE]] or [[CLEAR]] are used as the arrays are removed completely. +* [[_PRESERVE]] allows the [[UBOUND|upper]] and [[LBOUND|lower]] boundaries of an array to be changed. The number of dimensions cannot change. +* [[$DYNAMIC]] arrays must be [[REDIM]]ensioned if [[ERASE]] or [[CLEAR]] are used as the arrays are removed completely. +{{PageExamples}} ''Example:'' [[REDIM]]ing a $DYNAMIC array using [[_PRESERVE]] to retain previous array values. {{CodeStart}} '' '' {{Cl|REM}} {{Cl|$DYNAMIC}} 'create dynamic arrays only @@ -35,7 +35,7 @@ The '''$DYNAMIC''' Metacommand allows the creation of dynamic(changeable) array {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[$STATIC]], [[$INCLUDE]] * [[DIM]], [[REDIM]], [[_DEFINE]] * [[STATIC]] diff --git a/internal/help/$ELSE.txt b/internal/help/$ELSE.txt index 0cdc9ac64..a24e3a42b 100644 --- a/internal/help/$ELSE.txt +++ b/internal/help/$ELSE.txt @@ -1,35 +1 @@ -'''$ELSE''' is precompiler command, which determines which sections of code inside its blocks are included into our code for compiling. - - -{{PageSyntax}} -:: $IF variable = expression THEN... -::. -:: $ELSE -::. -:: $END IF - -* $ELSE must follow a valid $IF statement -* There can only be one $ELSE in an $IF-$ELSEIF-$ELSE-$END IF block, and it must be the last block selection before the $END IF. $ELSEIF ''can not'' follow $ELSE. - - -''Example 1:'' -{{CodeStart}} '' '' -{{Cl|$IF}} WIN THEN - {{Cl|CONST}} Slash = "\" -{{Cl|$ELSE}} - {{Cl|CONST}} Slash = "/" -{{Cl|$END IF}} - -{{Cl|PRINT}} "The proper slash for your operating system is "; Slash -{{CodeEnd}} - -For the above, the CONST slash is defined by the automatic internal flag (WIN), which tells us what operating system we're using. On a windows PC, the Slash will be the backslash; for any other OS it will be the forward slash. - - -''See also:'' -* [[$LET]] -* [[$IF]] -* [[$ELSEIF]] -* [[$END IF]] - -{{PageNavigation}} \ No newline at end of file +#REDIRECT [[$IF]] \ No newline at end of file diff --git a/internal/help/$ELSEIF.txt b/internal/help/$ELSEIF.txt index 316910ff7..a24e3a42b 100644 --- a/internal/help/$ELSEIF.txt +++ b/internal/help/$ELSEIF.txt @@ -1,43 +1 @@ -'''$ELSEIF''' is precompiler command, which determines which sections of code inside its blocks are included into our code for compiling. - - -{{PageSyntax}} -:: $IF variable = expression THEN... -::. -::.$ELSEIF variable = expression THEN... -::. -:: $ELSE -::. -:: $END IF - -* $ELSEIF must follow a valid $IF or $ELSEIF statement. -* If $ELSE is used, it must be used as the last conditional check before $END IF. $ELSEIF ''can non'' come after $ELSE. - -''Example 1:'' -{{CodeStart}} '' '' -{{Cl|$IF}} WIN AND 32Bit THEN - {{Cl|CONST}} Slash = "\" - {{Cl|CONST}} OS = "Windows 32Bit" -{{Cl|$ELSEIF}} WIN AND 64Bit THEN - {{Cl|CONST}} Slash = "\" - {{Cl|CONST}} OS = "Windows 64Bit" -{{Cl|$ELSEIF}} 32Bit THEN - {{Cl|CONST}} Slash = "\" - {{Cl|CONST}} OS = "Non-Windows 32Bit" -{{Cl|$ELSE}} - {{Cl|CONST}} Slash = "/" - {{Cl|CONST}} OS = "Non-Windows 64Bit" -{{Cl|$END IF}} - -{{Cl|PRINT}} "The proper slash for your operating system is "; Slash; " and you're running on a "; OS; " operating system." -{{CodeEnd}} - - - -''See also:'' -* [[$LET]] -* [[$IF]] -* [[$ELSE]] -* [[$END IF]] - -{{PageNavigation}} \ No newline at end of file +#REDIRECT [[$IF]] \ No newline at end of file diff --git a/internal/help/$END_IF.txt b/internal/help/$END_IF.txt index 57d2211a3..a24e3a42b 100644 --- a/internal/help/$END_IF.txt +++ b/internal/help/$END_IF.txt @@ -1,22 +1 @@ -'''$END IF''' is precompiler command, which determines which sections of code inside its blocks are included into our code for compiling. - - -{{PageSyntax}} -:: $IF variable = expression THEN... -::. -::.$ELSEIF variable = expression THEN... -::. -:: $ELSE -::. -:: $END IF - -* $END IF denotes the end of a valid precompiler $IF block. - - -''See also:'' -* [[$LET]] -* [[$IF]] -* [[$ELSE]] -* [[$ELSEIF]] - -{{PageNavigation}} \ No newline at end of file +#REDIRECT [[$IF]] \ No newline at end of file diff --git a/internal/help/$IF.txt b/internal/help/$IF.txt index dde0c40d5..baca220db 100644 --- a/internal/help/$IF.txt +++ b/internal/help/$IF.txt @@ -1,23 +1,29 @@ -'''$IF''' is precompiler command, which determines which sections of code inside its blocks are included into our code for compliing. +'''$IF''' is precompiler [[Metacommand|metacommand]], which determines which sections of code inside its blocks are included into the final code for compliing. {{PageSyntax}} -:: $IF variable = expression THEN... -::. -::. -::. -:: $END IF +:[[$IF]] variable = expression THEN +:. +:[[$ELSEIF]] variable = expression THEN +:. +:[[$ELSE]] +:. +:[[$END IF]] * $IF is the start of a precompiler code block which includes or excludes sections of code from being compiled. -* Currently there is no single line $IF statement. $IF must be in a valid $IF THEN... $END IF block to work properly. -* Like all other metacommands, you can not use more than one metacommand per line. Use of : to separate multi-line statements onto one line will not work with $IF (or any other metacommand). -* Variable names can contain numbers, letters, and periods -- in any order! +* There is no single line $IF statement. $IF must be in a valid $IF THEN...$END IF block to work properly. +* Like all other metacommands, you can not use more than one metacommand per line. '''Use of : to separate statements in a single line is not allowed.''' +* Variable names can contain numbers, letters, and periods -- in any order. * Expressions can contain one set of leading and/or trailing quotes; and any number of numbers, letters, and periods, in any order. -* The precompiler comes with some preset values which can be used to help determine which code blocks to include/exclude for us. These are: '''WIN''' or '''WINDOWS''' if the user is running QB64 in a windows environment. '''LINUX''' if the user is running QB64 in a Linux environment. '''MAC''' or '''MACOSX''' if the user is running QB64 in a Mac environment. '''32BIT''' if the user is running a 32-bit version of QB64. '''64BIT''' if the user is running a 64-bit version of QB64. - +* The precompiler comes with some preset values which can be used to help determine which code blocks to include/exclude for us. These are: '''WIN''' or '''WINDOWS''' if the user is running QB64 in a Windows environment. '''LINUX''' if the user is running QB64 in a Linux environment. '''MAC''' or '''MACOSX''' if the user is running QB64 in a macOS environment. '''32BIT''' if the user is running a 32-bit version of QB64. '''64BIT''' if the user is running a 64-bit version of QB64. +* [[$END IF]] denotes the end of a valid precompiler $IF block. +* [[$ELSEIF]] must follow a valid $IF or $ELSEIF statement. +* If [[$ELSE]] is used, it must be used as the last conditional check before $END IF. $ELSEIF cannot come after $ELSE. +** There can only be one $ELSE in an '''$IF-$ELSEIF-$ELSE-$END IF''' block, and it must be the last block selection before the $END IF. $ELSEIF cannot follow $ELSE. +{{PageExamples}} ''Example 1:'' {{CodeStart}} '' '' {{Cl|$LET}} ScreenMode = 32 @@ -31,13 +37,11 @@ {{Cl|PRINT}} "Hello World" {{CodeEnd}} -Explanation: -If you look at the code above, you'll see that we have the same CONST defined twice inside the program. Normally, we get an error if we try to define a CONST more than once, but the $IF condition here is CHOOSING which CONST we want inside our program. +''Explanation:'' The same CONST is defined twice inside the program. Normally, defining a CONST more than once generates an error, but the $IF condition here is choosing which CONST will be inside the final program. -AS long as Screenmode is 0, the program will exclude the code where CONST Red is defined as color 4. If Screenmode is 32, CONST Red will be defined as _RGB32(255, 0, 0). - -The $LET and $IF statements let us control the code that actually gets compiled, while excluding the other blocks completely. +As long as Screenmode is 0, the program will exclude the code where CONST Red is defined as color 4. If Screenmode is 32, CONST Red will be defined as _RGB32(255, 0, 0). +The [[$LET]] and $IF statements let the programmer control the code that actually gets compiled, while excluding the other blocks completely. ''Example 2:'' @@ -51,13 +55,12 @@ The $LET and $IF statements let us control the code that actually gets compiled, {{Cl|PRINT}} "The proper slash for your operating system is "; Slash {{CodeEnd}} -For the above, the CONST slash is defined by the automatic internal flags which tell us what operating system we're using. On a windows PC, the Slash will be the backslash; for any other OS it will be the forward slash. +''Explanation:'' For the above, the CONST slash is defined by the automatic internal flags which returns what operating system is being used at compile time. On a Windows PC, the Slash will be the backslash; for any other OS it will be the forward slash. -''See also:'' +{{PageSeeAlso}} * [[$LET]] -* [[$ELSE]] -* [[$ELSEIF]] -* [[$END IF]] +* [[Metacommand]]s + {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/$INCLUDE.txt b/internal/help/$INCLUDE.txt index 69fde324c..08f77fb8c 100644 --- a/internal/help/$INCLUDE.txt +++ b/internal/help/$INCLUDE.txt @@ -1,41 +1,39 @@ -'''$INCLUDE''' is a metacommand that is used to insert a source code file into your program which is then executed at the point of the insertion. +[[$INCLUDE]] is a metacommand that is used to insert a source code file into your program which is then executed at the point of the insertion. {{PageSyntax}} -:: {[[REM]] | [[REM|']] } $INCLUDE: 'sourcefile' +: {[[REM]] | [[REM|']] } $INCLUDE: '{{Parameter|sourceFile}}' -* Qbasic required that a comment or REM preceded all [[Metacommand]]s at the start of the program. -* The ''source file'' name MUST have REM or apostrophe comments around the text source file name. +{{PageDescription}} +* QBasic [[Metacommand|metacommands]] must be commented with [[REM]] or an apostrophe. +* The {{Parameter|sourceFile}} name must be enclosed in apostrophes and can include a path. * $INCLUDE is often used to add functions and subs from an external text QBasic code library. -* The source file included can contain any BASIC statement except [[GOTO]] -* QB 4.5 can use [[DECLARE]] SUB in BI files such as [[QB.BI]]. '''QB64''' ignores Qbasic's [[DECLARE]] statements. -* '''QB64 users can use all statements in their include files. See below.''' -* The $INCLUDE metacommand should be the only statement on a line since execution progresses ''after'' the code line. +* The $INCLUDE metacommand should be the only statement on a line. - -<center>'''How to $INCLUDE a BAS or Text file with a QB64 Program'''</center> -* '''QB64''' does not require a comment or [[REM]] before any [[Metacommand]]. '''Do NOT comment QB64 specific [[Metacommand]]s!''' -* The ''source file'' name MUST have REM or apostrophe comments around the text source file name. -* 1) Assemble your text code into a TEXT file and name it something with a '''.BI''' or '''.BM''' file name extension. -* 2) $INCLUDE any [[DEFINT]], [[DIM]], [[CONST]], [[SHARED]] arrays or [[DATA]] at the very '''beginning''' of the main program code. -* 3) $INCLUDE [[SUB]]s or [[FUNCTION]]s at the very bottom of the main program code '''AFTER any SUB procedures.''' -::: '''Note:''' [[TYPE]] definitions, [[DATA]] and [[DECLARE LIBRARY]] can be placed inside of sub-procedures. -* 4) '''Compile''' the program with the included text files '''in the QB64 folder!''' Save the text files to use them like '''Library files'''. -<center>'''Note: Once the program is compiled, the included text files are no longer needed with the program EXE.'''</center> +===How to $INCLUDE a BAS or Text file with a QB64 Program=== +* Assemble the code to be reused into a file. +* Common extensions are '''.BI''' (for declarations, usually included in the beginning of a program) or '''.BM''' (with SUBs and FUNCTIONs, usually included at the end of a program). +** Any extension can be used, as long as the file contains code in plain text (binary files are not accepted). +* $INCLUDE any [[DIM]], [[CONST]], [[SHARED]] arrays or [[DATA]] at the '''beginning''' of the main program code. +* $INCLUDE [[SUB]]s or [[FUNCTION]]s at the bottom of the main program code '''after any SUB procedures.''' +** '''Note:''' [[TYPE]] definitions, [[DATA]] and [[DECLARE LIBRARY]] can be placed inside of sub-procedures. +* '''Compile''' the program. +*''Note: Once the program is compiled, the included text files are no longer needed with the program EXE.'' -''Example:'' ''' '$INCLUDE:''' '[[QB.BI]]' +{{PageExamples}} +{{CodeStart}}''' '$INCLUDE:''' 'QB.BI'{{CodeEnd}} -''See Library Examples:'' -* [[SelectScreen]] (member $INCLUDE demo) -* [[FILELIST$ (function)]] (member FILE Search function) +===More examples=== +* [[SelectScreen]] (member-contributed $INCLUDE demo) +* [[FILELIST$]] (member-contributed file search function) * [[SAVEIMAGE]] (SUB program that creates bitmaps) -''See also:'' +{{PageSeeAlso}} * [[INTERRUPT]], [[INTERRUPTX]] * [[TYPE]], [[DIM]] * [[Metacommand]] diff --git a/internal/help/$LET.txt b/internal/help/$LET.txt index 3895c628b..014023e5b 100644 --- a/internal/help/$LET.txt +++ b/internal/help/$LET.txt @@ -1,40 +1,27 @@ -'''$LET''' is precompiler command, which is now usable by modern day [[cavemen]] to help include and exclude which sections of code compiles in their program based on OS/bit-size or other predefined conditions. +[[$LET]] is precompiler command, which is now usable by modern day [[cavemen]] to help include and exclude which sections of code compiles in their program based on OS/bit-size or other predefined conditions. {{PageSyntax}} -:: $LET variable = expression +: [[$LET]] variable = expression -* $LET a = 12 sets a precompiler variable "a" to the value of 12. This variable is ONLY valid for the precompiler itself and does NOTHING to affect the values of any variable/constant which might also be called "a" in the program. -* Variable names can contain numbers, letters, and periods -- in any order! $LET 3.2 = TRUE is a perfectly valid variable and expression. -* Expressions can contain one set of leading and/or trailing quotes; and any number of numbers, letters, and periods, in any order. $LET 3.2 = "TRUE" is also perfectly, but $LET 3.2 = ""TRUE"" will error. (See the double quotes?) - -''Example 1:'' -{{CodeStart}} '' '' -{{Cl|$LET}} ScreenMode = 32 -{{Cl|$IF}} ScreenMode = 0 THEN - {{Cl|CONST}} Red = 4 -{{Cl|$ELSEIF}} ScreenMode = 32 THEN - {{Cl|CONST}} Red = _RGB32(255,0,0) -{{Cl|$END IF}} - -{{Cl|COLOR}} Red -{{Cl|PRINT}} "Hello World" -{{CodeEnd}} - -Explaination: -If you look at the code above, you'll see that we have the same CONST defined inside the program. Normally, we get an error if we try to define a CONST more than once, but the $IF condition here is CHOOSING which CONST we want inside our program. - -AS long as Screenmode is 0, the program will exclude the code where CONST Red is defined as color 4. If Screenmode is 32, CONST Red will be defined as _RGB32(255, 0, 0). - -The $LET and $IF statements let us control the code that actually gets compiled, while excluding the other blocks completely. +{{PageDescription}} +* Unlike [[LET]], [[$LET]] is not optional. +* $LET a = 12 sets a precompiler variable "a" to the value of 12. This variable is only valid for the precompiler itself and does nothing to affect the values of any variable/constant which might also be called "a" in the program. +* Variable names can contain numbers, letters, and periods in any order. [[$LET]] '''3.2 = TRUE''' is a perfectly valid variable and expression. +* Expressions can contain one set of leading and/or trailing quotes; and any number of numbers, letters, and periods, in any order. [[$LET]] '''3.2 = "TRUE"''' is also perfectly valid, but [[$LET]] '''3.2 = ""TRUE""''' will error because of the double quotes. -''See also:'' -* [[Cavemen]] +{{PageExamples}} +* See example 1 in [[$IF]]. + + +{{PageSeeAlso}} * [[$IF]] * [[$ELSE]] * [[$ELSEIF]] * [[$END IF]] +* [[Cavemen]] + {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/$RESIZE.txt b/internal/help/$RESIZE.txt index bcb2334d3..4a2159aac 100644 --- a/internal/help/$RESIZE.txt +++ b/internal/help/$RESIZE.txt @@ -1,19 +1,112 @@ -The '''$RESIZE''' metacommand determines if a program window can be resized by the user in '''QB64 GL''' only. +The [[$RESIZE]] [[Metacommand|metacommand]] determines if a program window can be resized by the user. {{PageSyntax}} - -::: '''$RESIZE:'''{ON|OFF|STRETCH|SMOOTH} +: [[$RESIZE]]:{ON|OFF|STRETCH|SMOOTH} +{{PageDescription}} * $RESIZE:ON is used to allow the program window to be resized by a program user. Otherwise it cannot be changed. -* $RESIZE:OFF (default) is used when the program's window size cannot be changed by the user. +* $RESIZE:OFF ('''default''') is used when the program's window size cannot be changed by the user. * $RESIZE:STRETCH the screen will be stretched to fit the new window size with a 1 to 1 ratio of width and height. * $RESIZE:SMOOTH the screen will be stretched also, but with linear filtering applied to the pixels. -* '''QB64 GL''' programs only. Not available in QB64 SDL versions .954 and older. -''See also:'' +==Availability== +* '''Version 1.000 and up'''. + + +{{PageExamples}} +''Example:'' Resizing a program screen when the user changes it without clearing the entire screen image: +{{CodeStart}} +{{Cl|$RESIZE}}:ON + +{{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(160, 140, 32) +{{Cl|_DELAY}} 0.1 +{{Cl|_SCREENMOVE}} 20, 20 +{{Cl|_DISPLAY}} + +' CLEAR _RESIZE FLAG BY READING IT ONCE +temp& = {{Cl|_RESIZE (function)|_RESIZE}} + +DO + + {{Cl|_LIMIT}} 60 + + {{Cl|IF...THEN|IF}} CheckResize({{Cl|_SOURCE}}) = -1 {{Cl|THEN}} + {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} 10 + {{Cl|CIRCLE}} ({{Cl|RND}} * {{Cl|_WIDTH (function)|_WIDTH}}(0) - 1, {{Cl|RND}} * {{Cl|_HEIGHT}}(0) - 1), {{Cl|RND}} * 100 + 5, {{Cl|_RGB32}}({{Cl|RND}} * 255, {{Cl|RND}} * 255, {{Cl|RND}} * 255) + {{Cl|NEXT}} + {{Cl|ELSE}} + {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} 200 + {{Cl|PSET}} ({{Cl|RND}} * {{Cl|_WIDTH (function)|_WIDTH}}(0) - 1, {{Cl|RND}} * {{Cl|_HEIGHT}}(0) - 1), {{Cl|_RGB32}}({{Cl|RND}} * 255, {{Cl|RND}} * 255, {{Cl|RND}} * 255) + {{Cl|NEXT}} + {{Cl|END IF}} + + {{Cl|_DISPLAY}} + + k& = {{Cl|_KEYHIT}} + +{{Cl|LOOP}} {{Cl|UNTIL}} k& = 27 {{Cl|OR (boolean)|OR}} k& = 32 + +{{Cl|SYSTEM}} + + + +' ************************************************************************************************* +' * * +' * CheckResize: This FUNCTION checks if the user resized the window, and if so, recreates the * +' * ORIGINAL SCREEN image to the new window size. * +' * * +' * Developer Note: You must use $RESIZE:ON, $RESIZE:SMOOTH, or $RESIZE:SMOOTH at * +' * the beginning of your project for this to work. * +' * This FUNCTION only works in QB64 version 1.000 and up. * +' * * +' ************************************************************************************************* +{{Cl|FUNCTION}} CheckResize (CurrentScreen {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|LONG}}) + + ' *** Define local variable for temporary screen + {{Cl|DIM}} TempScreen {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|LONG}} + + CheckResize = 0 + + ' *** Check to see if the user resized the window. If so, change the SCREEN image to the correct size. + {{Cl|IF...THEN|IF}} {{Cl|_RESIZE (function)|_RESIZE}} {{Cl|THEN}} + + ' *** First, create a copy of the current {{Cl|SCREEN}} image. + TempScreen = {{Cl|_COPYIMAGE}}(CurrentScreen, 32) + + ' *** Set the {{Cl|SCREEN}} to the copied image, releasing the current SCREEN image. + {{Cl|SCREEN}} TempScreen + + ' *** Remove ({{Cl|TIMER (statement)|FREE}}) the original {{Cl|SCREEN}} image. + {{Cl|_FREEIMAGE}} CurrentScreen + + ' *** Create a new "original" {{Cl|SCREEN}} image. + CurrentScreen = {{Cl|_NEWIMAGE}}({{Cl|_RESIZEWIDTH}}, {{Cl|_RESIZEHEIGHT}}, 32) + + ' *** Set the {{Cl|SCREEN}} to the new "original" image, releasing the copied {{Cl|SCREEN}} image. + {{Cl|SCREEN}} CurrentScreen + + ' {{Cl|DRAW}} PREVIOUS {{Cl|SCREEN}} ON THE NEW ONE + {{Cl|_PUTIMAGE}} (0, 0), TempScreen, CurrentScreen + + {{Cl|_DISPLAY}} + + ' *** Remove ({{Cl|TIMER (statement)|FREE}}) the copied {{Cl|SCREEN}} image. + {{Cl|_FREEIMAGE}} TempScreen + + ' *** Tell the caller there was a resize + CheckResize = -1 + + {{Cl|END IF}} + + +{{Cl|END FUNCTION}} +{{CodeEnd}}{{small|Code by waltersmind}} + + +{{PageSeeAlso}} * [[_RESIZE]], [[_RESIZE (function)]] * [[_RESIZEWIDTH]], [[_RESIZEHEIGHT]] {{text|(functions return the requested dimensions)}} diff --git a/internal/help/$SCREENHIDE.txt b/internal/help/$SCREENHIDE.txt index 96e9d9f29..89b319e3b 100644 --- a/internal/help/$SCREENHIDE.txt +++ b/internal/help/$SCREENHIDE.txt @@ -1,16 +1,16 @@ -The '''$SCREENHIDE''' [[Metacommand]] can be used to hide the main program window throughout a program. +The [[$SCREENHIDE]] [[Metacommand|metacommand]] can be used to hide the main program window throughout a program. {{PageSyntax}} -::: $SCREENHIDE +: [[$SCREENHIDE]] -* $SCREENHIDE may be used at the start of a program to hide the main program window when using a [[$CONSOLE|console]] window. -* $SCREENHIDE must be used before the [[$SCREENSHOW]] [[Metacommand]] can be used! +* $SCREENHIDE may be used at the start of a program to hide the main program window when using a [[$CONSOLE|console]] window. * The [[_SCREENHIDE]] statement must be used before [[_SCREENSHOW]] can be used in sections of a program. -* '''QB64 [[Metacommand]]s require that commenting or [[REM]] NOT be used!''' +* '''QB64 [[Metacommand|metacommand]]s cannot be commented out with [[apostrophe]] or [[REM]]'''. +{{PageExamples}} ''Example:'' Hiding a program when displaying a message box in Windows. {{CodeStart}} '' '' {{Cl|$SCREENHIDE}} @@ -28,8 +28,8 @@ ExitProcess MessageBoxA(0, {{Cl|_OFFSET (function)|_OFFSET}}(s0), {{Cl|_OFFSET(f {{CodeEnd}}{{small|Code by Michael Calkins}} -''See also:'' -* [[$CONSOLE]], [[$SCREENSHOW]] {{text|(QB64 [[Metacommand]])}} +{{PageSeeAlso}} +* [[$CONSOLE]], [[$SCREENSHOW]] * [[_SCREENHIDE]], [[_SCREENSHOW]] * [[_CONSOLE]] diff --git a/internal/help/$SCREENSHOW.txt b/internal/help/$SCREENSHOW.txt index 5bb0fbcdf..8adf448cb 100644 --- a/internal/help/$SCREENSHOW.txt +++ b/internal/help/$SCREENSHOW.txt @@ -1,17 +1,18 @@ -The '''$SCREENSHOW''' [[Metacommand]] can be used to display the main program window throughout the program. +The [[$SCREENSHOW]] [[Metacommand|metacommand]] can be used to display the main program window throughout the program. {{PageSyntax}} -::: $SCREENSHOW +: $SCREENSHOW -* The Metacommand is intended to be used in a modular program when a screen surface is necessary in one or more modules. -* $SCREENSHOW can only be used AFTER [[$SCREENHIDE]] or [[_SCREENHIDE]] have been used in another program module! -* If [[$SCREENHIDE]] and $SCREENSHOW are used in the same program module the window will never be hidden. -* '''QB64 [[Metacommand]]s require that commenting or [[REM]] NOT be used!''' +{{PageDescription}} +* The metacommand is intended to be used in a modular program when a screen surface is necessary in one or more modules. +* $SCREENSHOW can only be used after [[$SCREENHIDE]] or [[_SCREENHIDE]] have been used in another program module. +* If [[$SCREENHIDE]] and then [[$SCREENSHOW]] are used in the same program module the window will not be hidden. +* '''QB64 [[Metacommand|metacommand]]s cannot be commented out with [[apostrophe]] or [[REM]].''' -''See also:'' +{{PageSeeAlso}} * [[$CONSOLE]], [[$SCREENHIDE]] (QB64 [[Metacommand]]s) * [[_SCREENHIDE]], [[_SCREENSHOW]] * [[_CONSOLE]] diff --git a/internal/help/$VIRTUALKEYBOARD.txt b/internal/help/$VIRTUALKEYBOARD.txt index 0793dd7fc..3bf065a54 100644 --- a/internal/help/$VIRTUALKEYBOARD.txt +++ b/internal/help/$VIRTUALKEYBOARD.txt @@ -1,20 +1,16 @@ {{DISPLAYTITLE:$VIRTUALKEYBOARD}} -The '''$VIRTUALKEYBOARD''' QB64 GL Metacommand turns the virtual keyboard ON or OFF in Android device programs. +The [[$VIRTUALKEYBOARD]] [[Metacommand|metacommand]] turns the virtual keyboard ON or OFF. {{PageSyntax}} -::: '''$VIRTUALKEYBOARD:'''{ON|OFF} +: [[$VIRTUALKEYBOARD]]:{ON|OFF} {{PageDescription}} -* If you haven't got an Android device and just want to try out the virtual keyboard add the following meta-command: $VIRTUALKEYBOARD:ON +* Places a virtual keyboard on screen, which can be used in touch-enabled devices like Windows tablets. - -{{PageErrors}} - - -''Example:'' +{{PageExamples}} {{CodeStart}} {{Cl|$VIRTUALKEYBOARD}}:ON @@ -23,6 +19,7 @@ The '''$VIRTUALKEYBOARD''' QB64 GL Metacommand turns the virtual keyboard ON or {{PageSeeAlso}} +* [[Metacommand]]s {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/ABS.txt b/internal/help/ABS.txt index 59e310452..33b197137 100644 --- a/internal/help/ABS.txt +++ b/internal/help/ABS.txt @@ -1,17 +1,18 @@ -The {{KW|ABS}} function returns the the unsigned numerical value of a variable or literal value. +The [[ABS]] function returns the the unsigned numerical value of a variable or literal value. {{PageSyntax}} -:{{Parameter|positive}} = '''ABS({{Parameter|numericalvalue}})''' +:{{Parameter|positive}} = [[ABS]]({{Parameter|numericalValue}}) {{PageDescription}} -* ABS always returns positive numerical values. The value can be any numerical type. +* [[ABS]] always returns positive numerical values. The value can be any numerical type. * Often used to keep a value positive when necessary in a program. -* Use [[SGN]] to determine a values sign when necessary. -* '''QB64''' allows programs to return only positive [[_UNSIGNED]] variable values using a [[DIM]] or {{KW|_DEFINE}} statement. +* Use [[SGN]] to determine a value's sign when necessary. +* '''QB64''' allows programs to return only positive [[_UNSIGNED]] variable values using a [[DIM]] or [[_DEFINE]] statement. +{{PageExamples}} ''Example:'' Finding the absolute value of positive and negative numerical values. {{CodeStart}} '' '' a = -6 @@ -28,7 +29,7 @@ c = {{Cl|ABS}}(c) {{PageSeeAlso}} * [[SGN]], [[DIM]] -* [[_UNSIGNED]] {{text|(integer types only)}} +* [[_UNSIGNED]] * [[_DEFINE]] * [[Mathematical Operations]] diff --git a/internal/help/ACCESS.txt b/internal/help/ACCESS.txt index e2d33fa1c..227671a16 100644 --- a/internal/help/ACCESS.txt +++ b/internal/help/ACCESS.txt @@ -1,22 +1,20 @@ -The '''ACCESS''' clause is used in a networking {{KW|OPEN}} statement. DOS 3.1 or above only! +#REDIRECT [[OPEN#File_ACCESS_and_LOCK_Permissions]] +The [[ACCESS]] clause is used in an [[OPEN]] statement when working over a network. {{PageSyntax}} :OPEN "file.dat" FOR APPEND ['''ACCESS {READ|WRITE}'''] AS #1 {{PageDescription}} +* Valid Options: +**Default: When specified, all other processes are denied file access. +**READ: When specified, read access is denied to other file procedures. +**WRITE: When specified, write access is denied to other file procedures. +**READ WRITE: When specified any access is denied to other file procedures. -''Valid Options:'' -*Default: When specified, all other processes are denied file access. -*READ: When specified, read access is denied to other file procedures. -*WRITE: When specified, write access is denied to other file procedures. -*READ WRITE: When specified any access is denied to other file procedures. - - -''Limitations:'' -* Requires that the DOS '''SHARED.EXE''' program be run for QBasic to use networking access modes. +===Limitations=== *If another process already has access to a specified file, program access is denied for that file OPEN access. A "Permission Denied" error 70 will be returned. A network program must be able to handle a denial of access error. diff --git a/internal/help/ALIAS.txt b/internal/help/ALIAS.txt index 488b48d20..f1428927b 100644 --- a/internal/help/ALIAS.txt +++ b/internal/help/ALIAS.txt @@ -1,8 +1,10 @@ -The '''ALIAS''' clause in a [[DECLARE LIBRARY]] statement block tells the program the name of the procedure used in the external library. +#REDIRECT [[DECLARE LIBRARY]] + +The [[ALIAS]] clause in a [[DECLARE LIBRARY]] statement block tells the program the name of the procedure used in the external library. {{PageSyntax}} -::: SUB ''pseudoname'' '''ALIAS''' ''actualname'' [(''parameters'')] +: SUB ''pseudoname'' [[ALIAS]] ''actualname'' [(''parameters'')] {{Parameters}} @@ -11,18 +13,28 @@ The '''ALIAS''' clause in a [[DECLARE LIBRARY]] statement block tells the progra * QB64 must use all parameters of imported procedures including optional ones. -''Description:'' +{{PageDescription}} * The ALIAS name clause is optional as the original library procedure name can be used. * The procedure name does not have to be inside of quotes when using [[DECLARE LIBRARY]]. -* QB64 does not support creating optional parameters at this time. +* QB64 does not support optional parameters. + + +==QBasic/QuickBASIC== * In Qbasic ALIAS was originally only used in a [[DECLARE (non-BASIC statement)]] library declarations. +{{PageExamples}} ''Example:'' Instead of creating a SUB with the Library statement inside of it, just rename it: {{CodeStart}} '' '' {{Cl|DECLARE LIBRARY}} - {{Cl|SUB}} MouseMove {{Cl|ALIAS}} SDL_WarpMouse ({{Cl|BYVAL}} xoffset&, {{Cl|BYVAL}} yoffset&) + {{Cl|SUB}} MouseMove {{Cl|ALIAS}} glutWarpPointer ({{Cl|BYVAL}} xoffset&, {{Cl|BYVAL}} yoffset&) {{Cl|DECLARE LIBRARY|END DECLARE}} + +{{Cl|DO}} {{Cl|UNTIL}} {{Cl|_SCREENEXISTS}}: {{Cl|LOOP}} +{{Cl|PRINT}} "Hit a key..." +{{Cl|SLEEP}} + +MouseMove 1, 1 {{CodeEnd}} :''Explanation:'' When a Library procedure is used to represent another procedure name use ALIAS instead. Saves creating a SUB! Just place your name for the procedure first with the actual Library name after ALIAS. diff --git a/internal/help/AND.txt b/internal/help/AND.txt index 8153e2e0a..99b6040c4 100644 --- a/internal/help/AND.txt +++ b/internal/help/AND.txt @@ -1,15 +1,14 @@ -The logical '''AND''' numerical operator compares two values in respect of their bits. If both bits at a certain position in both values are set, then that bit position is set in the result. +The logical [[AND]] numerical operator compares two values in respect of their bits. If both bits at a certain position in both values are set, then that bit position is set in the result. {{PageSyntax}} -:{{Parameter|result}} = '''{{Parameter|firstvalue}} AND {{Parameter|secondvalue}}''' - +:{{Parameter|result}} = {{Parameter|firstvalue}} AND {{Parameter|secondvalue}} {{PageDescription}} -* AND compares the bits of the {{Parameter|firstvalue}} against the bits of the {{Parameter|secondvalue}}, the result is stored in the {{Parameter|result}} variable. -* If both bits are on or binary 1 then the result is on or 1. -* All other conditions return 0 or the bit is off. +* [[AND]] compares the bits of the {{Parameter|firstvalue}} against the bits of the {{Parameter|secondvalue}}, the result is stored in the {{Parameter|result}} variable. +* If both bits are on (1) then the result is on (1). +* All other conditions return 0 (bit is off). * AND is often used to see if a bit is on by comparing a value to an exponent of 2. * Can turn off a bit by subtracting the bit on value from 255 and using that value to AND a byte value. @@ -17,6 +16,7 @@ The logical '''AND''' numerical operator compares two values in respect of their {{Template:LogicalTruthTable}} +{{PageExamples}} ''Example 1:'' {{WhiteStart}} 101 @@ -26,7 +26,7 @@ The logical '''AND''' numerical operator compares two values in respect of their 001 {{WhiteEnd}} -:The 101 bit pattern equals 5 and the 011 bit pattern equals 3, it returns the bit pattern 001 which equals 1. Only the Least Significant Bits(LSB) match. So decimal values 5 AND 3 = 1. +:The 101 bit pattern equals 5 and the 011 bit pattern equals 3, it returns the bit pattern 001 which equals 1. Only the Least Significant Bits (LSB) match. So decimal values 5 AND 3 = 1. ''Example 2:'' @@ -37,13 +37,13 @@ The logical '''AND''' numerical operator compares two values in respect of their ---------- 11101011 {{WhiteEnd}} -:Both bits have to be set for the resulting bit to be set. You can use the AND operator to get one byte of a two byte integer this way: +:Both bits have to be set for the resulting bit to be set. You can use the [[AND]] operator to get one byte of a two byte integer this way: -:::::firstbyte = twobyteint AND 255 +::firstbyte = twobyteint AND 255 :Since 255 is 11111111 in binary, it will represent the first byte completely when compared with AND. -:To find the second(HI) byte's decimal value of two byte {{KW|INTEGER}}s use: secondbyte = twobyteint \ 256 +:To find the second (HI) byte's decimal value of two byte [[INTEGER]]s use: secondbyte = twobyteint \ 256 ''Example 3:'' Finding the binary bits on in an [[INTEGER]] value. @@ -64,15 +64,13 @@ The logical '''AND''' numerical operator compares two values in respect of their {{OutputStart}} 0001011110100111 {{OutputEnd}} -::''Note:'' The value of 32767 sets 15 bits. -1 sets all 16 bits. Negative values will all have the highest bit set. Use {{KW|LONG}} variables for input values to prevent overflow errors! - - +::''Note:'' The value of 32767 sets 15 bits. -1 sets all 16 bits. Negative values will all have the highest bit set. Use [[LONG]] variables for input values to prevent overflow errors. {{PageSeeAlso}} -*{{KW|OR}} (operator), {{KW|XOR}} (operator), {{KW|NOT}} (operator) -*{{KW|AND (boolean)}} -*[[Binary]], [[Boolean]] +* [[OR]], [[XOR]], [[NOT]] {{text|(logical operators)}} +* [[AND (boolean)]] +* [[Binary]], [[Boolean]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/AND_(boolean).txt b/internal/help/AND_(boolean).txt index 57507bfc1..14fbf0098 100644 --- a/internal/help/AND_(boolean).txt +++ b/internal/help/AND_(boolean).txt @@ -3,22 +3,22 @@ The [[AND (boolean)|AND]] conditonal operator is used to include another evaluat {{PageSyntax}} -::: IF {{Parameter|condition}} '''AND''' {{Parameter|condition2}} +: IF {{Parameter|condition}} [[AND (boolean)|AND]] {{Parameter|condition2}} {{PageDescription}} -* If {{Parameter|condition}} [[AND (boolean)|AND]] {{Parameter|condition2}} are True then the evaluation returns True. +* If {{Parameter|condition}} [[AND (boolean)|AND]] {{Parameter|condition2}} are true then the evaluation returns true (-1). * {{Parameter|condition}} and {{Parameter|condition2}} can also contain their own AND evaluations. -* Both the IF evaluation and the AND evaluation must be True for the statement to be True. +* Both the IF evaluation and the AND evaluation must be true for the statement to be true. * Statements can use parenthesis to clarify an evaluation. -* [[AND]] and '''OR''' cannot be used to combine command line operations. -* '''A double AND syntax error may be ignored and create a QB64 compiler error!''' +* [[AND (boolean)]] and [[OR (boolean)]] cannot be used to combine command line operations. * Not to be confused with the [[AND]] and [[OR]] numerical operations. {{Template:RelationalTable}} +{{PageExamples}} ''Example:'' Using AND in an IF statement. {{CodeStart}} @@ -55,6 +55,7 @@ True {{PageSeeAlso}} +* [[AND]], [[OR]] {{text|(logical operators)}} * [[OR (boolean)]], [[XOR (boolean)]] * [[IF...THEN]] diff --git a/internal/help/ANY.txt b/internal/help/ANY.txt index 882150056..df71d8b76 100644 --- a/internal/help/ANY.txt +++ b/internal/help/ANY.txt @@ -1,3 +1,11 @@ +#REDIRECT [[Data types]] + +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + ANY disables type checking for a variable used in a [[SUB]] or [[FUNCTION]] declaration. @@ -5,7 +13,7 @@ ANY disables type checking for a variable used in a [[SUB]] or [[FUNCTION]] decl :: variable AS ANY -* [[Keywords currently not supported by QB64|Currently NOT supported in QB64]] +* [[Keywords currently not supported by QB64|Not supported in QB64.]] * ANY can become any type variable or value later in the program. * Commonly used in [[SUB]] or [[FUNCTION]] [[DECLARE|declarations]] to not type a parameter. diff --git a/internal/help/APPEND.txt b/internal/help/APPEND.txt index e927fa4c5..13c4b074d 100644 --- a/internal/help/APPEND.txt +++ b/internal/help/APPEND.txt @@ -1,16 +1,20 @@ -APPEND is used in an output type [[OPEN]] statement to add data to the end of a file. +#REDIRECT [[OPEN#File_Access_Modes]] + +[[APPEND]] is used in an output type [[OPEN]] statement to add data to the end of a file. {{PageSyntax}} -::: OPEN FileName$ '''FOR APPEND''' AS #1 +: [[OPEN]] {{Parameter|fileName$}} '''FOR APPEND''' AS #1 +{{PageDescription}} * Creates an empty file using the filename if none exists. * Mode places new data after the previous data in the file. * Mode can use [[PRINT (file statement)]], [[WRITE (file statement)]] or [[PRINT USING (file statement)]] to output file data or text. -''See also:'' [[OUTPUT]], [[RANDOM]], [[INPUT (file mode)]], [[BINARY]] +{{PageSeeAlso}} +[[OUTPUT]], [[RANDOM]], [[INPUT (file mode)]], [[BINARY]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/AS.txt b/internal/help/AS.txt index 85b06b23e..5960c201d 100644 --- a/internal/help/AS.txt +++ b/internal/help/AS.txt @@ -1,39 +1,29 @@ -The '''AS''' keyword defines a variable value's [[type]]. +The [[AS]] keyword defines a variable data [[type]]. -* AS defines the variable or array type AS [[_BIT]], [[_BYTE]], [[INTEGER]], [[LONG]], [[_INTEGER64]], [[SINGLE]], [[DOUBLE]], [[_FLOAT]], [[STRING]] or [[ANY]]. - +{{PageDescription}} +* AS defines the variable or array type AS [[_BIT]], [[_BYTE]], [[INTEGER]], [[LONG]], [[_INTEGER64]], [[SINGLE]], [[DOUBLE]], [[_FLOAT]] or [[STRING]]. * Specifies a variable's [[type]] in a declarative statement or parameter list using: +** [[DIM]] or [[REDIM]] +** [[DECLARE LIBRARY]] +** [[SUB]] +** [[FUNCTION]] +** [[TYPE]] +** [[SHARED]] +** [[COMMON SHARED]] +** [[STATIC]] -:::::[[DIM]] or [[REDIM]] - -:::::[[DECLARE]] - -:::::[[SUB]] - -:::::[[FUNCTION]] - -:::::[[TYPE]] - -:::::[[DEF FN]] - -:::::[[SHARED]] - -:::::[[COMMON SHARED]] - -:::::[[STATIC]] +===Details=== +* Specifies a '''[[parameter]]''' variable's type in a [[SUB]] or [[FUNCTION]] procedure. '''Cannot be used to define a function's [[type]]''' +* Specifies an element's type in a user-defined data [[TYPE]]. +* Assigns a file number to a file or device in an [[OPEN]] statement. +* Specifies a field name in a random-access record (see [[FIELD]]) +* Specifies a new file name when you rename a file (see [[NAME]]) +* '''NOTE: Many QBasic keywords can be used as variable names if they are created as [[STRING]]s using the suffix '''$'''. You cannot use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements.''' -* Specifies a '''[[parameter]]''' variable's type in a [[SUB]] or [[FUNCTION]] procedure. '''Cannot be used to define a function's [[TYPE]]!''' -* Specifies an element's type in a user-defined data type: [[TYPE]] -* Assigns a file number to a file or device in an [[OPEN]] statement: -* Specifies a field name in a random-access record: [[FIELD]] -* Specifies a new file name when you rename a file: [[NAME]] -* '''NOTE: Many Qbasic keyword variable names CAN be used with a [[STRING]] suffix($) ONLY! You CANNOT use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements!''' - - -''See also:'' +{{PageSeeAlso}} * [[DIM]], [[REDIM]] * [[_DEFINE]] * [[BYVAL]], [[TYPE]] diff --git a/internal/help/ASC.txt b/internal/help/ASC.txt index 6fe03b6b6..e0bbd3fb5 100644 --- a/internal/help/ASC.txt +++ b/internal/help/ASC.txt @@ -1,22 +1,22 @@ -The '''ASC''' function returns the {{KW|ASCII}} code number of a certain {{KW|STRING}} text character or a keyboard press. +The [[ASC]] function returns the [[ASCII]] code number of a certain [[STRING]] text character or a keyboard press. {{PageSyntax}} -:: code% = '''ASC('''''text$''[, ''position%'']''')''' +: {{Parameter|code%}} = [[ASC]]({{Parameter|text$}}[, {{Parameter|position%}}]) -* String ''text'' [[STRING|string]] character parameter must have a length of at least 1 byte or an error occurs. -* '''In QB64''' an optional byte ''position'' [[INTEGER]] parameter greater than 0 can specify the ASCII code of any character in a string to be returned. -* If the optional position parameter is omitted, ASC will return the [[ASCII]] code of the '''first''' [[STRING]] character only. -* [[ASCII]] code [[INTEGER]] or [[_UNSIGNED]] [[_BYTE]] values returned will range from 0 to 255 only. -* ASC returns 0 when reading [[ASCII]] 2 byte codes returned by [[INKEY$]] when the arrow, F function, Home\Page keys are used. -:: Use QB64's position parameter to read the second byte if necessary. {{Text|IF ASC(key$) <nowiki>=</nowiki> 0 THEN byte2 <nowiki>=</nowiki> ASC(key$, 2)|green}} +* {{Parameter|text$}} [[STRING|string]] character parameter must have a length of at least 1 byte or an error occurs. +* '''In QB64''' the optional byte {{Parameter|position%}} [[INTEGER]] parameter greater than 0 can specify the ASCII code of any character in a string to be returned. +* If the optional {{Parameter|position%}} parameter is omitted, ASC will return the [[ASCII]] code of the first [[STRING]] character. +* [[ASCII]] code [[INTEGER]] or [[_UNSIGNED]] [[_BYTE]] values returned range from 0 to 255. +* ASC returns 0 when reading [[ASCII]] 2 byte codes returned by [[INKEY$]] when the arrow, function, Home/Page keys are used. +** Use QB64's {{Parameter|position%}} parameter to read the second byte if necessary. {{Text|IF ASC(key$) <nowiki>=</nowiki> 0 THEN byte2 <nowiki>=</nowiki> ASC(key$, 2)|green}} * In '''QB64''' ASC string byte position reads are about '''5 times faster''' than [[MID$]] when parsing strings. See [[MID$]] ''Example 2''. {{PageErrors}} -* If the function is used to read an '''empty string value''' an illegal function call [[ERROR Codes|error]] will occur! [[INKEY$]] returns an empty string when a key is not pressed. -* '''QB64''' ''position'' parameters must range from 1 to the [[LEN|length]] of the string being read or an illegal function call [[ERROR Codes|error]] will occur. +* If the function is used to read an '''empty string value''' an illegal function call [[ERROR Codes|error]] will occur. [[INKEY$]] returns an empty string when a key is not pressed. +* '''QB64''''s {{Parameter|position%}} parameters must range from 1 to the [[LEN|length]] of the string being read or an illegal function call [[ERROR Codes|error]] will occur. {{WhiteStart}}' '''ASCII Keyboard Codes''' @@ -88,6 +88,7 @@ The '''ASC''' function returns the {{KW|ASCII}} code number of a certain {{KW|ST :In '''QB64''', [[CVI]] can be used to get the [[_KEYDOWN]] 2-byte code value. Example: IF _KEYDOWN([[CVI]]([[CHR$]](0) + "P")) THEN +{{PageExamples}} ''Example 1:'' How ASC can be used to find any ASCII code in a string of characters using QB64. {{CodeStart}} '' '' {{Cl|PRINT}} ASC("A") @@ -96,7 +97,6 @@ The '''ASC''' function returns the {{KW|ASCII}} code number of a certain {{KW|ST {{CodeEnd}} ''Returns:'' - {{OutputStart}} 65 66 @@ -128,11 +128,10 @@ DO {{CodeEnd}} {{small|Code by Ted Weissgerber}} -''Explanation:'' The keypress read loop checks that ASC will not read an empty string. That would create a program error. {{KW|SLEEP}} reduces CPU memory usage between keypresses. Normal byte codes returned are indicated by the IF statement when ASC returns a value. Otherwise the routine will return the two byte ASCII code. The extended keyboard keys(Home pad, Arrow pad and Number pad), Function keys or Ctrl, Alt or Shift key combinations will return two byte codes. Ctrl + letter combinations will return control character codes 1 to 26. +''Explanation:'' The keypress read loop checks that ASC will not read an empty string. That would create a program error. [[SLEEP]] reduces CPU memory usage between keypresses. Normal byte codes returned are indicated by the IF statement when ASC returns a value. Otherwise the routine will return the two byte ASCII code. The extended keyboard keys(Home pad, Arrow pad and Number pad), Function keys or Ctrl, Alt or Shift key combinations will return two byte codes. Ctrl + letter combinations will return control character codes 1 to 26. ''Example 3:'' Reading only numerical values input by a program user. - {{CodeStart}} DO: {{Cl|SLEEP}} ' requires a keypress to run loop once K$ = {{Cl|{{Cl|INKEY$}}}} @@ -152,12 +151,11 @@ DO {{Cl|LOOP}} {{Cl|UNTIL}} code = 13 {{Cl|AND}} L '' '' {{CodeEnd}} -''Explanation:'' [[SLEEP]] waits for a keypress allowing background programs to use the processor time. It also keeps the press in the keyboard buffer for [[INKEY$]] to read and guarantees that ASC will not read an empty string value to create an error. Filtered codes 48 to 57 are only number characters. One decimal point is allowed by using the flag. Code 8 is a backspace request which is ignored if the entry has no characters. If it is allowed it removes the last character from the entry and the screen. The loop exits when the user presses the [Enter] key and the entry has a length. '''Try to do that with [[INPUT]]!''' +''Explanation:'' [[SLEEP]] waits for a keypress allowing background programs to use the processor time. It also keeps the press in the keyboard buffer for [[INKEY$]] to read and guarantees that ASC will not read an empty string value to create an error. Filtered codes 48 to 57 are only number characters. One decimal point is allowed by using the flag. Code 8 is a backspace request which is ignored if the entry has no characters. If it is allowed it removes the last character from the entry and the screen. The loop exits when the user presses the [Enter] key and the entry has a length. - -''See also:'' -* [[ASC (statement)]] {{text|(QB64 only)}} +{{Parameter|See also:'' }} +* [[ASC (statement)]] * [[_KEYHIT]], [[_KEYDOWN]] * [[MID$]], [[CHR$]], [[INKEY$]] * [[VAL]], [[STRING$]] diff --git a/internal/help/ASC_(statement).txt b/internal/help/ASC_(statement).txt index 017f7d774..a65afb4d4 100644 --- a/internal/help/ASC_(statement).txt +++ b/internal/help/ASC_(statement).txt @@ -1,19 +1,19 @@ -The {{KW|ASC (statement)|ASC}} statement allows a '''QB64''' program to change a character at any position of a predefined {{KW|STRING}}. - +The [[ASC (statement)|ASC]] statement allows a '''QB64''' program to change a character at any position of a [[STRING]] variable. {{PageSyntax}} -::: '''ASC({{Parameter|string_expression$}}'''[, {{Parameter|position%}}]''') =''' {{Parameter|code%}} +: [[ASC (statement)|ASC]]({{Parameter|stringExpression$}}[, {{Parameter|position%}}]) = {{Parameter|code%}} {{PageDescription}} -* The ''string expression'' variable must have been previously defined and cannot be an empty string(""). -* The ''position'' parameter is optional. If no position is used, the left-most position(1) is assumed. -* The ''position'' cannot be zero or greater than the string's length [[LEN]] or an [[ERROR Codes|Illegal function error]] will occur. -* The [[ASCII]] replacement ''code%'' value can be any [[INTEGER]] value from 0 to 255. +* The {{Parameter|stringExpression$}} variable's value must have been previously defined and cannot be an empty string (""). +* {{Parameter|position%}} is optional. If no position is used, the leftmost character at position 1 is assumed. +* {{Parameter|position%}} cannot be zero or greater than the string's [[LEN|length]] or an [[ERROR Codes|Illegal function error]] will occur. +* The [[ASCII]] replacement {{Parameter|code%}} value can be any [[INTEGER]] value from 0 to 255. * Some [[ASCII]] control characters will not [[PRINT]] a character or may format the [[SCREEN]]. [[_PRINTSTRING]] can print them graphically. +{{PageExamples}} ''Example:'' Demonstrates how to change existing text characters one letter at a time. {{CodeStart}} a$ = "YZC" @@ -35,7 +35,7 @@ The {{KW|ASC (statement)|ASC}} statement allows a '''QB64''' program to change a {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[ASC]] {{text|(function)}} * [[MID$ (statement)]] * [[_PRINTSTRING]] diff --git a/internal/help/ATN.txt b/internal/help/ATN.txt index 2ccfe7617..181e9f18d 100644 --- a/internal/help/ATN.txt +++ b/internal/help/ATN.txt @@ -1,22 +1,23 @@ -The {{KW|ATN}} or arctangent function returns the angle in radians of a numerical [[TAN|tangent]] value. +The [[ATN]] or arctangent function returns the angle in radians of a numerical [[TAN|tangent]] value. {{PageSyntax}} -:: radian_angle = '''ATN(''tangent!'')''' +: {{Parameter|radianAngle}} = [[ATN]]({{Parameter|tangent!}}) {{Parameters}} -* The return is that tangent value's ''angle'' in radians. -* ''tangent'' [[SINGLE]] or [[DOUBLE]] values are use by the function. EX:'''{{text|Pi <nowiki>=</nowiki> 4 * ATN(1)|green}}''' +* The return is the {{Parameter|tangent!}}'s angle in '''radians'''. +* {{Parameter|tangent!}} [[SINGLE]] or [[DOUBLE]] values are used by the function. EX:'''{{text|Pi <nowiki>=</nowiki> 4 * ATN(1)|green}}''' {{PageDescription}} * To convert from radians to degrees, multiply radians * (180 / &pi;). -* The ''tangent'' value would be equal to the tangent value of an angle. EX: '''{{text|[[TAN]](ATN(1)) <nowiki>=</nowiki> 1|green}}''' +* The ''tangent'' value would be equal to the tangent value of an angle. Ex: '''{{text|[[TAN]](ATN(1)) <nowiki>=</nowiki> 1|green}}''' * The function return value is between -&pi; / 2 and &pi; / 2. -''Example 1:'' When the [[TAN]]gent value equals 1, the line is drawn at a 45 degree angle(.7853982 radians) where [[SIN]] / [[COS]] = 1. +{{PageExamples}} +''Example 1:'' When the [[TAN]]gent value equals 1, the line is drawn at a 45 degree angle (.7853982 radians) where [[SIN]] / [[COS]] = 1. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 x = 100 * {{Cl|COS}}({{Cl|ATN}}(1)) @@ -25,12 +26,13 @@ y = 100 * {{Cl|SIN}}({{Cl|ATN}}(1)) {{CodeEnd}} -''Example 2:'' {{KW|ATN}} can be used to define &pi; in [[SINGLE]] or [[DOUBLE]] precision. The calculation can NOT be used as a [[CONST]]ant. +''Example 2:'' [[ATN]] can be used to define &pi; in [[SINGLE]] or [[DOUBLE]] precision. The calculation cannot be used as a [[CONST]]ant. {{CodeStart}} '' '' Pi = 4 * {{Cl|ATN}}(1) '{{Cl|SINGLE}} precision Pi# = 4 * {{Cl|ATN}}(1#) '{{Cl|DOUBLE}} precision PRINT Pi, Pi# '' '' {{CodeEnd}} +:''Note:'' You can use QB64's native [[_PI]] function. ''Example 3:'' Finds the angle from the center point to the mouse pointer. diff --git a/internal/help/Apostrophe.txt b/internal/help/Apostrophe.txt index 880689f67..c25473204 100644 --- a/internal/help/Apostrophe.txt +++ b/internal/help/Apostrophe.txt @@ -1,21 +1,23 @@ -The '''apostrophe''' is used to tell Qbasic to ignore a statement or programmer comment. +The '''apostrophe''' is used to tell the compiler to ignore a statement or programmer comment. + +{{PageDescription}} +* Allows programmer comments or temporary code removal. +* [[REM]] can also be used to "comment out" a line. +* QBasic [[Metacommand|metacommand]]s must be commented either with an apostrophe or [[REM]]. +* [[$INCLUDE]] requires an apostrophe before and after the included file name. -''Usage:'' COLOR 11: PRINT "Print this...." ' PRINT "Don't print this program comment!" +{{PageExamples}} +{{CodeStart}} +COLOR 11: PRINT "Print this...." ' PRINT "Don't print this program comment!" +{{CodeEnd}} {{OutputStart}} {{text|Print this....|aqua}} {{OutputEnd}} -* Allows programmer comments or temporary code removal. -* [[REM]] can also be used to "comment out" a line. -* [[Metacommand]]s require that they are commented either with an apostrophe or [[REM]]. -* [[$INCLUDE]] requires a "comment" apostrophe before and after the included file name also. - - -''See also:'' - +{{PageSeeAlso}} * [[Comma]], [[Semicolon]] * [[REM]] diff --git a/internal/help/BEEP.txt b/internal/help/BEEP.txt index 0b12a3b9f..c15df5d74 100644 --- a/internal/help/BEEP.txt +++ b/internal/help/BEEP.txt @@ -1,36 +1,24 @@ -The '''BEEP''' statement produces a beeping sound through the sound card(QB64) or PC speaker(QB) if it has one. +The [[BEEP]] statement produces a beep sound through the sound card. {{PageSyntax}} -:: [[BEEP]] +: [[BEEP]] {{PageDescription}} -* {{KW|BEEP}} can be placed anywhere to alert the user that there is something to do or an error has occurred. -* [[ASCII]] control character 7 can also create a {{KW|BEEP}} sound when you {{KW|PRINT}} it (See [[CHR$]]). -* In Windows it may produce a "thunk" warning sound when a Qbasic program is running in a {{KW|SCREEN}} 0 window. -* Newer PC's may not have an internal speaker to hear ANY Qbasic [[SOUND|sounds]]! -* '''QB64''' produces the actual "beep" sound through the PC's stereo speakers. -* To produce the BEEP sound character in a QBasic(.BAS) or a batch(.BAT) file using a '''DOS''' editor (or the QB IDE) press ''Ctrl + P'' then ''G.'' PRINT it inside of quotation marks to beep in QB. Use the character after ECHO in a batch file. '''Not in the QB64 IDE!''' - - -{{PageExamples}} - -''Example:'' Creating two beep sounds using [[BEEP]] and [[PRINT|printing]] the [[ASCII]] control character 7. -{{CodeStart}}'' '' -{{Cl|BEEP}} -{{Cl|PRINT}} {{Cl|CHR$}}(7) '' '' -{{CodeEnd}} - +* [[BEEP]] can be placed anywhere to alert the user that there is something to do or an error has occurred. +* '''QB64''' produces the actual "beep" sound through the PC's sound card, to emulate QBasic's beeping through the [https://en.wikipedia.org/wiki/PC_speaker PC speaker]. +==QBasic/QuickBASIC== +* Older programs may attempt to produce a BEEP by printing [[CHR$]](7) to the screen. This is no longer supported in QB64 after '''version 1.000'''. +** You may have to replace instances of PRINT CHR$(7) in older programs to the [[BEEP]] statement to maintain the legacy functionality. {{PageSeeAlso}} -* {{KW|SOUND}}, {{KW|PLAY}} -* {{KW|_SNDPLAY}} (play sound files) -* {{KW|_SNDRAW}} (play frequency waves) -* {{KW|CHR$}}, {{KW|ASCII}} (code table) +* [[SOUND]], [[PLAY]] +* [[_SNDPLAY]] {{text|(play sound files)}} +* [[_SNDRAW]] {{text|(play frequency waves)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/BINARY.txt b/internal/help/BINARY.txt index be05a6590..76d579c57 100644 --- a/internal/help/BINARY.txt +++ b/internal/help/BINARY.txt @@ -1,25 +1,24 @@ -{{KW|BINARY}} is used in an {{KW|OPEN}} statement to treat the file or port device as a {{KW|BINARY}}. +#REDIRECT [[OPEN#File_Access_Modes]] + +[[BINARY]] is used in an [[OPEN]] statement to work with the file or port device manipulating its bytes directly. {{PageSyntax}} -:{{KW|OPEN}} {{Parameter|filename$}} {{KW|FOR}} {{KW|BINARY}} {{KW|AS}} {{Parameter|#filenumber%}} +:[[OPEN]] {{Parameter|fileName$}} [[FOR]] [[BINARY]] [[AS]] {{Parameter|#fileNumber%}} {{PageDescription}} -* [[OPEN]] FOR BINARY creates the file if the filename$ does not exist. -* {{Parameter|filename$}} is the name of the file to open, but could also configure a port. -* {{Parameter|#filenumber%}} is the number that will represent the file when performing file operations. +* [[OPEN]] FOR BINARY creates the file if the {{Parameter|fileName$}} does not exist. +* {{Parameter|fileName$}} is the name of the file to open, but could also configure a port. +* {{Parameter|#fileNumber%}} is the number that will represent the file when performing file operations. * BINARY files use [[GET|GET #]] and [[PUT|PUT #]] to read or write the file at any byte position. -* '''QB64-GL''' allows [[LINE INPUT]] to be used for faster access to text file data. -* The number of bytes read or written depends on the byte [[LEN|length]] of the variable type used. -* When [[PUT]] is used with a variable, numerical values are converted to [[ASCII]] string types [[MKI$]], [[MKL$]], [[MKS$]], [[MKD$]] or [[_MK$]]. -* One byte [[ASCII]] {{KW|STRING}} data character values can be read as number values using {{KW|ASC}}(values from 0 to 255). -* Some files, like bitmaps, contain standard length file information headers. -* Qbasic's [[BSAVE]] or BINARY save files can be read using a BINARY mode. -* BINARY mode ignores any [[LEN]] = recordlength statement in the {{KW|OPEN}} statement. -* Ports can also be opened in {{KW|BINARY}} mode. See: {{KW|OPEN COM}} +* In '''version 1.000 and up''' you can use [[LINE INPUT]] in [[BINARY]] mode for faster access to text file data. +* QBasic's [[BSAVE]] or BINARY save files can be read using BINARY mode. +* BINARY mode ignores any [[LEN]] = recordlength statement in the [[OPEN]] statement. +* Ports can also be opened in [[BINARY]] mode. See: [[OPEN COM]] +{{PageExamples}} ''Example 1:'' Shows how a PUT variable value is converted to an [[ASCII]] string [[_MK$]] format in a BINARY file. {{CodeStart}} '' '' {{Cl|DIM}} int64 {{Cl|AS}} {{Cl|_INTEGER64}} diff --git a/internal/help/BLOAD.txt b/internal/help/BLOAD.txt index 43e783032..a096c3cac 100644 --- a/internal/help/BLOAD.txt +++ b/internal/help/BLOAD.txt @@ -1,34 +1,36 @@ -{{KW|BLOAD}} loads a binary graphics file created by {{KW|BSAVE}} to an array. +[[BLOAD]] loads a binary graphics file created by [[BSAVE]] to an array. + +==Legacy support== +* '''QB64 can load larger arrays directly from binary files using [[PUT]] # and [[GET]] # without BLOAD. For that reason, BLOAD isn't recommended practice anymore and is supported to maintain compatibility with legacy code.''' {{PageSyntax}} -::: '''BLOAD''' {{Parameter|Filename$}}''', [[VARPTR]]('''{{Parameter|ImageArray%(index)}}''')''' - +: [[BLOAD]] {{Parameter|fileName$}}, [[VARPTR]]({{Parameter|imageArray%({{Parameter|index}})}}) {{Parameters}} -* {{Parameter|Filename$}} is the name of the file that the image should be [[BSAVE]]d to. -* {{Parameter|ImageArray%(index)}} is the Integer [[arrays|array]] start index that holds the image you want to save. +* {{Parameter|fileName$}} is the name of the file that the image should be [[BSAVE]]d to. +* {{Parameter|imageArray%(index)}} is the [[INTEGER]] [[arrays|array]] start index to store the image loaded. {{PageDescription}} -* There MUST be an Integer array of adequate size (up to 26K) to hold the graphic data! -* A [[DEF SEG]] pointing to the array is required. [[DEF SEG]] = [[VARSEG]](ImageArray%(index)) +* There must be an [[INTEGER]] array of adequate size (up to 26K) to hold the graphic data. +* A [[DEF SEG]] pointing to the array is required. [[DEF SEG]] = [[VARSEG]](imageArray%(index)) * {{Parameter|index}} is the starting image element of the Array. Can also include RGB color settings at the start index. * Fullscreen images in [[SCREEN]] 12 require 3 file BLOADs. A 26K array can hold 1/3 of screen. * Custom RGB color settings can be embedded(indexed) at the start of the image array. * BLOAD can be used to load any array that was saved with [[BSAVE]], not just graphics. -* Array sizes are limited to 32767 Integer elements due to use of [[VARPTR]] in QB and '''QB64'''!. -* '''QB64''' can load larger arrays directly to and from binary files using [[PUT]] # and [[GET]] # without BLOAD. +* Array sizes are limited to 32767 Integer elements due to use of [[VARPTR]] in QBasic and '''QB64''''s emulated conventional memory. +{{PageExamples}} ''Example 1:'' Loading data to an array from a BSAVED file. {{CodeStart}} '' '' {{Cl|DEF SEG}} = {{Cl|VARSEG}}(Array(0)) {{Cl|BLOAD}} filename$, {{Cl|VARPTR}}(Array({{Cl|LBOUND}}(Array))) ' changeable index {{Cl|DEF SEG}} '' '' {{CodeEnd}} -:''Explanation:'' Referance any type of array that matches the data saved. Can work with Integer, Single, Double, Long, fixed length Strings or {{KW|TYPE}} arrays. {{KW|LBOUND}} determines the starting offset of the array or another index could be used. +:''Explanation:'' Referance any type of array that matches the data saved. Can work with Integer, Single, Double, Long, fixed length Strings or [[TYPE]] arrays. [[LBOUND]] determines the starting offset of the array or another index could be used. ''Example 2:'' Using a QB default colored image. @@ -41,8 +43,6 @@ : ''Note:'' [[PSET]] is used as a [[PUT (graphics statement)|PUT]] action that places the image over any background objects. - - {{PageSeeAlso}} * [[BSAVE]], [[OPEN]], [[BINARY]] * [[PUT]], [[GET]] {{text|(file statement)}} diff --git a/internal/help/BSAVE.txt b/internal/help/BSAVE.txt index 8ec25559a..241493714 100644 --- a/internal/help/BSAVE.txt +++ b/internal/help/BSAVE.txt @@ -1,27 +1,31 @@ -[[BSAVE]] saves the contents of an image array to a {{KW|BINARY}} file. +[[BSAVE]] saves the contents of an image array to a [[BINARY]] file. + + +==Legacy support== +* '''QB64 can save larger arrays directly to binary files using [[PUT]] # and [[GET]] # without BSAVE. For that reason, BSAVE isn't recommended practice anymore and is supported to maintain compatibility with legacy code. {{PageSyntax}} -::: '''BSAVE''' {{Parameter|savefile$}}''', [[VARPTR]]'''({{Parameter|Array(index)}})''',''' {{Parameter|Filesize&}} +: [[BSAVE]] {{Parameter|saveFile$}}, [[VARPTR]]({{Parameter|array(index)}}), {{Parameter|fileSize&}} {{Parameters}} -* ''savefile$'' is the STRING file name of the file designated to be created. -* ''Array(index)'' is the image [[arrays|array]] that already holds the [[GET (graphics statement)|GET]] image data. -* ''Filesize'' must be a bit over twice the size of the elements used in an {{KW|INTEGER}} [[Arrays|array]]. +* {{Parameter|saveFile$}} is the STRING file name of the file designated to be created. +* {{Parameter|array(index)}} is the image [[arrays|array]] that already holds the [[GET (graphics statement)|GET]] image data. +* {{Parameter|fileSize&}} must be a bit over twice the size of the elements used in an [[INTEGER]] [[Arrays|array]]. {{PageDescription}} * To place image data into the array, use [[GET (graphics statement)|GET]] to store a box area image of the screen. * [[SCREEN]] 12 can only GET 1/3 of the screen image at one time using a 26K array. * Image arrays are [[DIM]]ensioned as [[INTEGER]]. Use [[DEFINT]] when working with large graphic arrays. -* Any arrays can be saved, but Image arrays are most common. +* Any arrays can be saved, but image arrays are most common. * [[DEF SEG]] = [[VARSEG]] must be used to designate the array segment position in memory. -* [[VARPTR]] returns the Array index offset of the memory segment. Array sizes are limited to 32767 Integer elements due to the use of [[VARPTR]] in QB and '''QB64'''!. -* '''QB64''' can load larger arrays directly to and from binary files using [[PUT]] # and [[GET]] # without BSAVE. - * [[BSAVE]] files can later be opened with {{KW|BLOAD}}. +* [[VARPTR]] returns the array index offset of the memory segment. Array sizes are limited to 32767 Integer elements due to the use of [[VARPTR]] in QBasic and '''QB64''''s emulated conventional memory. +* [[BSAVE]] files can later be opened with [[BLOAD]]. +{{PageExamples}} ''Example 1:'' Saving array data to a file quickly. {{CodeStart}} '' '' LB% = {{Cl|LBOUND}}(Array) @@ -31,11 +35,10 @@ {{Cl|BSAVE}} filename$, {{Cl|VARPTR}}(Array(LB%)), filesize& ' changeable index {{Cl|DEF SEG}} '' '' {{CodeEnd}} -: ''Explanation:'' Procedure determines the filesize from the array size automatically. {{KW|LBOUND}} is used with {{KW|UBOUND}} to determine array size and byte size. Works with any type of array except variable length Strings. Great for saving program data fast! +: ''Explanation:'' Procedure determines the filesize from the array size automatically. [[LBOUND]] is used with [[UBOUND]] to determine array size and byte size. Works with any type of array except variable-length strings. Used for saving program data fast. - -''Example 2:'' {{KW|BSAVE}}ing a bitmap and calculating the file size +''Example 2:'' [[BSAVE]]ing a bitmap and calculating the file size {{CodeStart}} '' '' {{Cl|DEF SEG}} = {{Cl|VARSEG}}(Image(0)) {{Cl|PSET}}(BMPHead.PWidth - 1, BMPHead.PDepth - 1) 'color lower right corner if black @@ -47,7 +50,46 @@ {{Cl|DEF SEG}} '' '' {{CodeEnd}} -: ''Explanation:'' The {{KW|FOR...NEXT|FOR}} loop reads backwards through the image array until it finds a value not 0. The {{KW|LONG}} {{Parameter|ArraySize&}} value is doubled and 200 is added. {{Parameter|BMPhead.PWidth}} and {{Parameter|BMPhead.PDepth}} are found by reading the bitmap's information header using a {{KW|TYPE}} definition. See [[Bitmaps]]. +: ''Explanation:'' The [[FOR...NEXT|FOR]] loop reads backwards through the image array until it finds a value not 0. The [[LONG]] {{Parameter|ArraySize&}} value is doubled and 200 is added. {{Parameter|BMPhead.PWidth}} and {{Parameter|BMPhead.PDepth}} are found by reading the bitmap's information header using a [[TYPE]] definition. See [[Bitmaps]]. + + +''Example 3:'' Using [[PUT]] and [[GET]] to write and read array data from a file without using BSAVE or [[BLOAD]]: +{{CodeStart}} +{{Cl|KILL}} "example2.BIN" 'removes old image file! + +{{Cl|SCREEN}} 13 +{{Cl|OPTION BASE}} 0 +{{Cl|REDIM}} Graphic%(1001) 'REDIM makes array resize-able later + +{{Cl|LINE}} (0, 0)-(10, 10), 12, B 'create image +{{Cl|GET (graphics statement)|GET}}(0, 0)-{{Cl|STEP}}(10, 10), Graphic%() 'get image to array + +{{Cl|FOR...NEXT|FOR}} i% = 1000 {{Cl|TO}} 0 {{Cl|STEP}} -1 'reverse read array for size needed + {{Cl|IF...THEN|IF}} Graphic%(i%) <> 0 {{Cl|THEN}} {{Cl|EXIT}} {{Cl|FOR...NEXT|FOR}} 'find image color not black +{{Cl|NEXT}} +size% = i% + 4 'size plus 2 integers(4 bytes) for dimensions +{{Cl|REDIM}} {{Cl|_PRESERVE}} Graphic%(size%) 'resize existing array in QB64 only! + +{{Cl|OPEN}} "example2.BIN" {{Cl|FOR...NEXT|FOR}} {{Cl|BINARY}} {{Cl|AS}} #1 ' {{Cl|PUT}} to a file +{{Cl|PUT}} #1, , Graphic%() +{{Cl|CLOSE}} + +{{Cl|OPEN}} "example2.BIN" {{Cl|FOR...NEXT|FOR}} {{Cl|BINARY}} {{Cl|AS}} #2 'GET array and {{Cl|PUT}} to screen +{{Cl|DIM}} CopyBin%({{Cl|LOF}}(2) \ 2) 'create new array sized by half of file size +{{Cl|GET}} #2, , CopyBin%() +{{Cl|PUT (graphics statement)|PUT}}(100, 100), CopyBin%(), {{Cl|PSET}} +fsize% = {{Cl|LOF}}(2) +{{Cl|CLOSE}} + +K$ = {{Cl|INPUT$}}(1) 'Press any key +{{Cl|FOR...NEXT|FOR}} i = 0 {{Cl|TO}} 20 'read all 3 arrays + {{Cl|PRINT}} Graphic%(i); CopyBin%(i) +{{Cl|NEXT}} +{{Cl|PRINT}} "Array:"; size%, "File:"; fsize% +{{CodeEnd}}{{small|Code by Ted Weissgerber}} +: ''Explanation:'' A 10 by 10 pixel box is saved to an array using the [[GET (graphics statement)]] and written to a BINARY file using [[PUT]] #1. Then [[GET]] #1 places the file contents into another INTEGER array and places it on the screen with the [[PUT (graphics statement)]]. + +: The array contents: 88 is the width in the GET array for [[SCREEN]] 13 which needs divided by 8 in that mode only. The area is actually 11 X 11. The array size needed can be found by looping backwards through the array until a color value is found. '''{{text|IF array(i) <> 0 THEN EXIT FOR|green}}''' (66 integers) or by dividing the created BINARY file size in half (134 bytes) when known to be array sized already. {{PageSeeAlso}} diff --git a/internal/help/BYVAL.txt b/internal/help/BYVAL.txt index bc28ef6b3..d828836d4 100644 --- a/internal/help/BYVAL.txt +++ b/internal/help/BYVAL.txt @@ -1,38 +1,39 @@ -The '''BYVAL''' statement is used to pass a numerical parameter's value with procedures made in other programming languages. +The [[BYVAL]] statement is used to pass a numerical parameter's value with procedures made in other programming languages. {{PageSyntax}} -:: SUB Procedure_Name ('''BYVAL''' ''variable1'', '''BYVAL''' ''variable2'') +: SUB ProcedureName ([[BYVAL]] {{Parameter|variable1}}, [[BYVAL]] {{Parameter|variable2}}) {{PageDescription}} * '''QB64''' can only use BYVAL in [[DECLARE LIBRARY]] procedures that add DLL or Operating System API functions. * Supported with [[DECLARE LIBRARY]] [[SUB]] and [[FUNCTION]] procedure declarations when passing '''numerical values only'''. * Passing numerical values BYVAL assures that the original numerical variable value is not changed by another procedure. -* Use [[parenthesis]] around program [[SUB]] or [[FUNCTION]] parameters passed BY VALUE. Ex: ''CALL Procedure ((x&), (y&))'' - - -''Historical:'' -* Qbasic versions below 7 do not use BYVAL unless the [[SUB]] program referred to is from a different programming language. -* PDS versions can use BYVAL as it is intended in any [[SUB]] or [[FUNCTION]] parameters. -* BYVAL can also be used with [[ABSOLUTE]] in Qbasic only. +* Use [[parenthesis]] around program [[SUB]] or [[FUNCTION]] parameters passed '''by value'''. Ex: ''CALL Procedure ((x&), (y&))'' {{PageErrors}} -* '''Do not use BYVAL before [[STRING]] or [[TYPE]] variables or in regular prograam [[SUB]] or [[FUNCTION]] parameters!''' -* '''Many Qbasic keyword variable names CAN be used with a [[STRING]] suffix($) ONLY! You CANNOT use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements!''' +* '''Do not use BYVAL before [[STRING]] or [[TYPE]] variables or in regular prograam [[SUB]] or [[FUNCTION]] parameters.''' +* '''NOTE: Many QBasic keywords can be used as variable names if they are created as [[STRING]]s using the suffix '''$'''. You cannot use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements.''' +==QBasic/QuickBASIC== +* QBasic versions below 7 do not use BYVAL unless the [[SUB]] program referred to is from a different programming language. +* PDS versions can use BYVAL as it is intended in any [[SUB]] or [[FUNCTION]] parameters. +* BYVAL could also be used with [[ABSOLUTE]] in QBasic. + + +{{PageExamples}} ''Example 1:'' BYVAL is used to preserve the values sent to an external procedure so they remain the same after they are used: {{CodeStart}} '' '' -{{Cl|DECLARE LIBRARY}} +{{Cl|DECLARE LIBRARY}} "SDL" {{Cl|SUB}} MouseMove {{Cl|ALIAS}} SDL_WarpMouse ({{Cl|BYVAL}} xoffset&, {{Cl|BYVAL}} yoffset&) {{Cl|DECLARE LIBRARY|END DECLARE}} {{CodeEnd}} -: ''Note:'' Since the DLL library was already used by QB64 SDL(up to v.954), it did not require a DLL name. GL would! +: ''Note:'' The DLL call above uses the SDL library, which was included with QB64 up to version 0.954. Won't work with '''version 1.000 and up'''. -''Example 2:'' Passing parameters "by value" using [[parenthesis|brackets]] when calling a [[SUB]] or [[FUNCTION]] in Qbasic or QB64. +''Example 2:'' Passing parameters "by value" using [[parenthesis|brackets]] when calling a [[SUB]] or [[FUNCTION]] in QBasic or QB64. {{CodeStart}} '' '' {{Cl|CALL}} MySUB (a%, (b%), (c%)) 'CALL SUB b and c stay 0 after sub @@ -50,7 +51,7 @@ Inside procedure: 1 1 1 Inside procedure: 2 1 1 After procedures: 2 1 0 {{OutputEnd}} -:''Explanation:'' Both SUB calls pass just the '''values''' of b% and c% to the procedure. The first variable, a%, is passed by '''reference''' (the default) so the value was changed by the SUB procedure. Brackets can only be used in the [[CALL]] or function reference! +:''Explanation:'' Both SUB calls pass just the '''values''' of b% and c% to the procedure. The first variable, a%, is passed by '''reference''' (the default) so the value was changed by the SUB procedure. Brackets can only be used in the [[CALL]] or function reference. {{PageSeeAlso}} diff --git a/internal/help/CALL.txt b/internal/help/CALL.txt index 212f257b6..d2e45fa61 100644 --- a/internal/help/CALL.txt +++ b/internal/help/CALL.txt @@ -1,24 +1,26 @@ -{{KW|CALL}} sends code execution to a subroutine procedure in a program. In '''QB64''' the subroutine doesn't need to be declared. +[[CALL]] sends code execution to a subroutine procedure in a program. In '''QB64''' the subroutine doesn't need to be declared. {{PageSyntax}} -::: '''CALL {{Parameter|ProcedureName}}''' ['''('''{{Parameter|parameters}}, {{Parameter|passed}},...''')'''] +: [[CALL]] {{Parameter|ProcedureName}} ({{Parameter|parameter1}}, {{Parameter|parameter2}},...)] + +===Alternative syntax=== +: {{Parameter|ProcedureName}} {{Parameter|parameter1}}, {{Parameter|parameter2}},...] -''Non-call Syntax:'' - -::: '''{{Parameter|ProcedureName}}''' [{{Parameter|parameters}}, {{Parameter|passed}},...] - - -* CALL requires that {{KW|SUB}} program parameters be enclosed in brackets(parenthesis). -* CALL is NOT required to call a subprocedure. Use the SUB-procedure name and list any parameters without parenthesis. +* CALL requires [[SUB]] program parameters to be enclosed in brackets (parenthesis). +* CALL is not required to call a subprocedure. Use the SUB-procedure name and list any parameters without parenthesis. * Neither syntax can be used to call [[GOSUB]] linelabel sub procedures. -* To pass by values, both syntaxes require that each of those variable names be enclosed in parenthesis. -* PDS or Quickbasic 7 up can use [[BYVAL]] to pass by values instead of reference. -* Quickbasic 4.5 can use [[BYVAL]] only for procedures created in Assembly or another language. -* Qbasic requires [[CALL ABSOLUTE]] only. It does not have to be [[DECLARE]]d. +* To pass parameters by value, instead of by reference, enclose passed variables in parenthesis. +==QBasic/QuickBASIC== +* PDS or Quickbasic 7 up could use [[BYVAL]] to pass variables by values instead of reference. +* QuickBASIC 4.5 could use [[BYVAL]] only for procedures created in Assembly or another language. +* QBasic required [[CALL ABSOLUTE]] only. It did not have to be [[DECLARE]]d. + + +{{PageExamples}} ''Example:'' How parameters are passed in two [[SUB]] calls, one with CALL using brackets and one without CALL or brackets: {{CodeStart}} '' '' {{Cl|DIM}} a {{Cl|AS}} {{Cl|INTEGER}} 'value not shared with SUB @@ -53,8 +55,6 @@ Hello World! :The variable '''{{Parameter|c}}''' is the [[SUB]] parameter variable that passes values into the sub. Its value could be changed by the passed parameter value or inside of the subroutine. The un-shared '''{{Parameter|c}}''' variable value outside of the sub is irrelevant within the subroutine. -:''Note:'' CALL doesn't need to be used in order to call a subroutine. Just using the name of the sub with parameters and no brackets will do: '''{{text|helloworld a|green}}''' - {{PageSeeAlso}} * [[SUB]], [[FUNCTION]] diff --git a/internal/help/CALLS.txt b/internal/help/CALLS.txt index 46fac8a5c..15e854908 100644 --- a/internal/help/CALLS.txt +++ b/internal/help/CALLS.txt @@ -1,24 +1,24 @@ -{{KW|CALLS}} is a statement that transfers control to a procedure written in a different programming language. +'''This page is maintained for historic purposes. The keyword is not supported in QB64.''' + + +---- + + +[[CALLS]] is a statement that transfers control to a procedure written in a different programming language. {{PageSyntax}} -:{{KW|CALLS}} {{Parameter|name}} [({{Parameter|argumentlist}})] - - -* [[Keywords currently not supported by QB64|Currently NOT supported in QB64]] -* The arguments are passed by reference as far addresses, unlike {{KW|CALL}} which passes arguments by value as default. You cannot use {{KW|BYVAL}} or {{KW|SEG}} in a {{KW|CALLS}} argumentlist. - - - -{{KW|CALLS}} is the same as using {{KW|CALL}} with a {{KW|SEG}} before each argument. - +:[[CALLS]] {{Parameter|name}} [({{Parameter|argumentList}})] +* [[Keywords currently not supported by QB64|Not supported in QB64.]] +* The arguments are passed by reference as far addresses, unlike [[CALL]] which passes arguments by value as default. You cannot use [[BYVAL]] or [[SEG]] in a [[CALLS]] argumentList. +* [[CALLS]] is the same as using [[CALL]] with a [[SEG]] before each argument. {{PageSeeAlso}} -*{{KW|DECLARE (non-BASIC statement)}} -*{{KW|CALL}} +*[[DECLARE (non-BASIC statement)]] +*[[CALL]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CALL_ABSOLUTE.txt b/internal/help/CALL_ABSOLUTE.txt index 3bc6a95a6..6fdfc2a6e 100644 --- a/internal/help/CALL_ABSOLUTE.txt +++ b/internal/help/CALL_ABSOLUTE.txt @@ -1,209 +1,26 @@ -'''CALL ABSOLUTE''' is used to access Interrupts on the computer or execute assembly type procedures. +[[CALL ABSOLUTE]] is used to access interrupts on the computer or execute assembly type procedures. {{PageSyntax}} -: '''CALL ABSOLUTE([{{Parameter|argument_list}},] {{Parameter|integer_offset}})''' +: [[CALL ABSOLUTE]]([{{Parameter|argumentList}},] {{Parameter|integerOffset}}) + + +==Legacy support== +* [[CALL ABSOLUTE]] is implemented to support older code and is not recommended practice. To handle mouse input, the '''use [[_MOUSEINPUT]] and related functions'''. {{PageDescription}} * [[CALL]] and parameter brackets are required in the statement. -* {{Parameter|argument_list}} contains the list of arguments passed to the procedure. -* {{Parameter|integer_offset}} contains the offset from the current code segment, set by [[DEF SEG]] and [[SADD]], to the starting location of the called procedure. -* Qbasic and '''QB64''' have the Absolute statement built in and require no library. -* QuickBASIC requires the QB.QLB Quick Library, loaded with the <tt>/L</tt> switch. -* '''NOTE: QB64 does not currently support INT 33h mouse functions above 3 or {{KW|BYVAL}} in an ABSOLUTE statement!''' - - -''Example 1:'' Typical ABSOLUTE mouse program demonstrates the AX% mouse functions in QuickBASIC 4.x and QBasic 1.x: -{{CodeStart}} -{{Cl|DECLARE}} {{Cl|SUB}} MouseDriver (AX%, BX%, CX%, DX%, LB%, RB%, EX%) -{{Cl|DIM}} {{Cl|SHARED}} mouse$ ' Hardware communications resource string (created in SUB MouseDriver) -{{Cl|DIM}} {{Cl|SHARED}} CX%, DX%, LB%, RB% ' CX = column, DX = row, LB and RB are left and right buttons -{{Cl|SCREEN (statement)|SCREEN}} 12 - -MouseDriver 1, BX%, CX%, DX%, LB%, RB%, 1 ' EX% = 1 initiates the mouse. Otherwise use EX% = 0 - ' ----------------------- DEMO CODE ---------------------- -{{Cl|COLOR}} 10: {{Cl|LOCATE}} 1, 36: {{Cl|PRINT}} "H = Hide, S = Show, M = Move, L = Limit area" -{{Cl|COLOR}} 6: {{Cl|LOCATE}} 2, 10: {{Cl|PRINT}} "Hold mouse button down for total: P = Presses, R = Releases" -{{Cl|COLOR}} 13: {{Cl|LOCATE}} 29, 30: {{Cl|PRINT}} "Click or [Esc] EXIT!"; -{{Cl|CIRCLE}} (220, 150), 90, 10 ' use radius and center coordinates to find circle later -{{Cl|LOCATE}} 9, 22: {{Cl|PRINT}} "Click in circle" -{{Cl|COLOR}} 12: {{Cl|LOCATE}} 27, 10: {{Cl|PRINT}} "Show the mouse the same number of times it was Hidden!" -{{Cl|COLOR}} 14 - -{{Cl|DO...LOOP|DO}}: Funct$ = {{Cl|UCASE$}}({{Cl|INKEY$}}) ' any keypress....keeps loop running for mouse - - MouseDriver 3, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 3 reads mouse every loop - {{Cl|LOCATE}} 1, 2: {{Cl|PRINT}} "LB "; LB% ' left button value 0 or 1 pressed - {{Cl|LOCATE}} 1, 29: {{Cl|PRINT}} "RB "; RB% ' right button value 0 or 1 pressed - {{Cl|LOCATE}} 1, 10: {{Cl|PRINT}} "COL"; CX% ' column coordinate - {{Cl|LOCATE}} 1, 20: {{Cl|PRINT}} "ROW"; DX% ' row coordinate - {{Cl|IF...THEN|IF}} CX% >= 230 {{Cl|AND (boolean)|AND}} CX% <= 390 {{Cl|AND (boolean)|AND}} DX% >= 445 {{Cl|AND (boolean)|AND}} DX% <= 460 {{Cl|AND (boolean)|AND}} LB% {{Cl|THEN}} {{Cl|EXIT DO}} - {{Cl|SELECT CASE}} Funct$ - {{Cl|CASE}} "S": MouseDriver 1, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 1 show mouse - {{Cl|CASE}} "H": MouseDriver 2, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 2 hide mouse(accumulates) - {{Cl|CASE}} "M": CX% = 220: DX% = 150 ' set CX% and DX% to circle center - MouseDriver 4, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 4 moves mouse pointer to a coordinate - {{Cl|CASE}} "P": BX% = -1 - {{Cl|IF...THEN|IF}} LB% {{Cl|THEN}} BX% = 0: {{Cl|IF...THEN|IF}} RB% {{Cl|THEN}} BX% = 1 - MouseDriver 5, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 5 read button presses since last read - {{Cl|COLOR}} 6: {{Cl|LOCATE}} 29, 10: {{Cl|PRINT}} "Presses ="; BX%; {{Cl|SPACE$}}(2); - {{Cl|CASE}} "R": BX% = -1 - {{Cl|IF...THEN|IF}} LB% {{Cl|THEN}} BX% = 0: {{Cl|IF...THEN|IF}} RB% {{Cl|THEN}} BX% = 1 - MouseDriver 6, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 6 read button releases since last read - {{Cl|COLOR}} 6: {{Cl|LOCATE}} 29, 10: {{Cl|PRINT}} "Releases ="; BX%; {{Cl|SPACE$}}(2); - {{Cl|CASE}} "L": limit = {{Cl|NOT}} limit ' alternates between partial to fullscreen cursor move area. - {{Cl|IF...THEN|IF}} limit {{Cl|THEN}} CX% = 100: DX% = 500 {{Cl|ELSE}} CX% = 0: DX% = 639 ' min and max column coordinates - MouseDriver 7, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 7 limit horizontal column area - {{Cl|IF...THEN|IF}} limit {{Cl|THEN}} CX% = 100: DX% = 400 {{Cl|ELSE}} CX% = 0: DX% = 479 ' min and max row coordinates - MouseDriver 8, BX%, CX%, DX%, LB%, RB%, 0 ' AX% = 8 limit vertical row area - - {{Cl|END SELECT}} - - ' CALCULATING WHEN THE POINTER IS INSIDE OF THE CIRCLE - ' Pythagorean calculation: X ^ 2 + Y ^ 2 <= Radius ^ 2 for a position inside circle - XX& = ((CX% - 220) ^ 2) + ((DX% - 150) ^ 2) ' 220 and 150 are circle center coordinates - {{Cl|COLOR}} 11: {{Cl|LOCATE}} 22, 8 - {{Cl|PRINT}} "Columns"; {{Cl|CHR$}}(253); " + Rows"; {{Cl|CHR$}}(253); " <= Radius"; {{Cl|CHR$}}(253); " : IF"; XX&; "<= 8100 THEN "; - {{Cl|IF...THEN|IF}} XX& <= 8100 {{Cl|THEN}} ' 90 ^ 2 = 8100 is the circle radius squared - {{Cl|PRINT}} "Over Circle"; {{Cl|SPACE$}}(7) - {{Cl|IF...THEN|IF}} LB% = 1 {{Cl|THEN}} {{Cl|COLOR}} 12 ' left mouse button pressed in circle - {{Cl|IF...THEN|IF}} RB% = 1 {{Cl|THEN}} {{Cl|COLOR}} 13 ' right mouse button pressed in circle - {{Cl|ELSE}}: {{Cl|PRINT}} "Out of Circle"; {{Cl|SPACE$}}(5): {{Cl|COLOR}} 14 ' when mouse is not over circle - {{Cl|END IF}} - {{Cl|LOOP}} {{Cl|UNTIL}} Funct$ = {{Cl|CHR$}}(27) ' escape - {{Cl|SYSTEM}} - ' -------------------- END DEMO CODE ----------------- - -MouseData: -{{Cl|DATA}} 55,89,E5,8B,5E,0C,8B,07,50,8B,5E,0A,8B,07,50,8B -{{Cl|DATA}} 5E,08,8B,0F,8B,5E,06,8B,17,5B,58,1E,07,CD,33,53 -{{Cl|DATA}} 8B,5E,0C,89,07,58,8B,5E,0A,89,07,8B,5E,08,89,0F -{{Cl|DATA}} 8B,5E,06,89,17,5D,CA,08,00 - - -{{Cl|SUB}} MouseDriver (AX%, BX%, CX%, DX%, LB%, RB%, EX%) - {{Cl|IF...THEN|IF}} EX% = 1 {{Cl|THEN}} ' initiate mouse once. EX normally = 0 - ' mouse$ = Hardware communications resource string - {{Cl|RESTORE}} MouseData ' restore MouseDATA - mouse$ = {{Cl|SPACE$}}(57) ' defines fixed length as 57 bytes - {{Cl|FOR...NEXT|FOR}} i% = 1 {{Cl|TO}} 57 - {{Cl|READ}} a$ ' read data for communication string - H$ = {{Cl|CHR$}}({{Cl|VAL}}("&H" + a$)) ' get DATA hex ASCII character - {{Cl|MID$ (statement)|MID$}}(mouse$, i%, 1) = H$ - {{Cl|NEXT}} i% - {{Cl|END IF}} - {{Cl|DEF SEG}} = {{Cl|VARSEG}}(mouse$) - {{Cl|CALL ABSOLUTE|CALL Absolute}}(AX%, BX%, CX%, DX%, {{Cl|SADD}}(mouse$)) 'get coordinates and buttons - {{Cl|DEF SEG}} - {{Cl|IF...THEN|IF}} EX% = 1 {{Cl|THEN}} - {{Cl|LOCATE}} 29, 60 - {{Cl|IF...THEN|IF}} AX% {{Cl|THEN}} - {{Cl|PRINT}} "Mouse Found"; ' AX = -1 IF FOUND - {{Cl|ELSE}} : {{Cl|BEEP}}: {{Cl|PRINT}} "Mouse not found"; : {{Cl|SYSTEM}} - {{Cl|END IF}} - {{Cl|END IF}} - LB% = BX% {{Cl|AND}} 1 ' positive 1 return values - RB% = (BX% {{Cl|AND}} 2) \ 2 - MB% = (BX% {{Cl|AND}} 4) \ 4 -{{Cl|END SUB}} - -{{CodeEnd}} -{{small|Code by: Ted Weissgerber}} -:::'''NOTE: QB64 does not currently support functions above AX% = 3 in above ABSOLUTE demo!''' - -{{OutputStart}} - LB 0 COL 84 ROW 140 RB 0 H = Hide, S = Show, M = Move, L = Limit area - Hold mouse button down for total: P = Presses, R = Releases - - - - - - - - - Click in circle - - - - - - - - - - - - - Columns^2 + Rows^2 <= Radius^2 : IF 18596 <= 8100 THEN Out of Circle - - - - - - Show the mouse the same number of times it was Hidden! - - Click or [Esc] EXIT! Mouse Found - -{{OutputEnd}} -''Explanation:'' The circle isn't shown in this output screen, but when you run the example you can move the mouse into a circle in the middle of the screen and the text will change color to reflect that you are inside the circle, you can also use the mousebuttons and the color will change. - - -''Example 2:'' An Absolute substitution for INTERRUPT that can be used by all QB versions including PDS(7.1): - -{{CodeStart}} - -{{Cl|TYPE}} regs - AX {{Cl|AS}} {{Cl|INTEGER}} ' mouse function call - CX {{Cl|AS}} {{Cl|INTEGER}} ' mouse column position - DX {{Cl|AS}} {{Cl|INTEGER}} ' mouse row position - BX {{Cl|AS}} {{Cl|INTEGER}} ' mouse button press - SP {{Cl|AS}} {{Cl|INTEGER}} ' Ignored - BP {{Cl|AS}} {{Cl|INTEGER}} - SI {{Cl|AS}} {{Cl|INTEGER}} - DI {{Cl|AS}} {{Cl|INTEGER}} - Flags {{Cl|AS}} {{Cl|INTEGER}} - DS {{Cl|AS}} {{Cl|INTEGER}} - ES {{Cl|AS}} {{Cl|INTEGER}} -{{Cl|END TYPE}} - -{{Cl|DIM}} R {{Cl|AS}} regs ' set dot variable to the TYPE - ' Program code - ' R.AX = 3 ' mouse read function = 3 - ' CALL INTX(R) - - -{{Cl|SUB}} INTX(R {{Cl|AS}} regs) - {{Cl|STATIC}} Code {{Cl|AS}} {{Cl|STRING}}, M() {{Cl|AS}} {{Cl|INTEGER}} - {{Cl|IF...THEN|IF}} {{Cl|LEN}}(Code) = 0 {{Cl|THEN}} ' setup only - {{Cl|DIM}} M(0 {{Cl|TO}} 26) {{Cl|AS}} {{Cl|INTEGER}} - Code = "5589E58B76069C061EB90B00FCAD50E2FC071F9D61CD" - - '* Change this to the desired interrupt hex address number * - Code = Code + "33" ' IN HEXadecimal form only! - ' mouse = "33"; DOS Services = "21" - - Code = Code + "609C1E0689E58E46168B7E2283C714B90B00FD58ABE2FC1F079D5DCA02" - {{Cl|DEF SEG}} = {{Cl|VARSEG}}(M(0)) - {{Cl|FOR...NEXT|FOR}} I = 0 {{Cl|TO}} 51 - {{Cl|POKE}} {{Cl|VARPTR}}(M(0)) + I, {{Cl|VAL}}("&H" + {{Cl|MID$}}(Code, I * 2 + 1, 2)) - {{Cl|NEXT}} - {{Cl|END IF}} ' end setup - {{Cl|DEF SEG}} = {{Cl|VARSEG}}(M(0)) - {{Cl|CALL ABSOLUTE}}(R, {{Cl|VARPTR}}(M(0))) - {{Cl|DEF SEG}} -{{Cl|END SUB}} '' '' -{{CodeEnd}} -{{small|Code by: Artelius}} -''Explanation:'' To read or send values use dot variable names. Such as R.AX, R.BX(buttons), R.CX (horizontal coordinate) and R.DX (vertical coordinate). It can use all of the mouse functions used in previous code demo. - -'''Note: The second example cannot currently be run in QB64 as "User defined types are invalid with Absolute"!''' +* {{Parameter|argumentList}} contains the list of arguments passed to the procedure. +* {{Parameter|integerOffset}} contains the offset from the current code segment, set by [[DEF SEG]] and [[SADD]], to the starting location of the called procedure. +* QBasic and '''QB64''' have the ABSOLUTE statement built in and require no library, like QuickBASIC did. +* '''NOTE: QB64 does not support INT 33h mouse functions above 3 or [[BYVAL]] in an ABSOLUTE statement. Registers are emulated.''' {{PageSeeAlso}} * [[SADD]], [[INTERRUPT]] * [[DECLARE (non-BASIC statement)]] +* [[_MOUSEINPUT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CASE.txt b/internal/help/CASE.txt index fe654b363..c6c807264 100644 --- a/internal/help/CASE.txt +++ b/internal/help/CASE.txt @@ -1,48 +1,27 @@ +#REDIRECT [[SELECT CASE#allCASES]] + [[CASE]] is used within a [[SELECT CASE]] block to specify a conditional value of the compared variable. {{PageSyntax}} - -:: '''CASE comparison_value(s)'''[:] execute_code_line_or_block - +: [[CASE]] {{Parameter|comparisonValues}}[:] {code} {{PageDescription}} - -*{{Parameter|value}} can be any literal string or number, depending on the value specified in the {{KW|SELECT CASE}} statement. +*{{Parameter|comparisonValues}} can be any literal string or number, depending on the value specified in the [[SELECT CASE]] statement. *Code is executed until the next case, so each case can handle multiple lines of code. -*CASE conditions normally are listed in some logical order going down the page. -*CASE order can affect the SELECT CASE code execution when more than one CASE can be true! This is specially true when multiple conditional operators, CASE IS or TO ranges are used! -* CASE lists can also be listed horizontally by using colon separators between cases. +*[[CASE]] conditions are normally listed in some logical order going down the page. +*[[CASE]] order can affect the SELECT CASE code execution when more than one CASE can be true. This is specially true when multiple conditional operators, CASE IS or TO ranges are used. +* [[CASE]] lists can also be listed horizontally by using colon separators between cases. * Supports individual CASE values and ranges or lists of values as below: -:* CASE value -:* CASE value1 [[TO]] value2 -:* CASE value1, value2, value3 -:* [[CASE IS]] value1 > value2 -:* [[CASE ELSE]] - - -''Relational Operators:'' Used in {{KW|CASE}} {{KW|IS}} evaluations Only. - -* > is Greater than -* < is Less than -* = is Equal to -* >= is Greater than or Equal to -* <= is Less than or Equal to -* <> is Not Equal to - - -''Multiple Conditional Operators:'' Used in {{KW|CASE}} {{KW|IS}} Only. - -* {{KW|AND (boolean)|AND}} can be used to add extra conditions to a {{KW|CASE}} {{KW|IS}} statement evaluation. -* {{KW|OR (boolean)|OR}} can be used to add alternate conditions to a {{KW|CASE}} {{KW|IS}} statement evaluation. -* Parenthesis are allowed in {{KW|CASE}} {{KW|IS}} statements to clarify an evaluation. -* The FIRST time a {{KW|CASE}} value matches the compared variable's value, that {{KW|CASE}} code is executed and {{KW|SELECT CASE}} is exited. - - -''Example:'' +** [[CASE]] value +** [[CASE]] value1 [[TO]] value2 +** [[CASE]] value1, value2, value3 +** [[CASE IS]] value1 > value2 +** [[CASE ELSE]] +* The first time a [[CASE]] value matches the compared variable's value, that [[CASE]] code is executed and [[SELECT CASE]] is exited, unless '''EVERYCASE''' is used. +{{PageExamples}} {{CodeStart}} - a = 100 {{Cl|SELECT CASE}} a {{Cl|CASE}} 1, 3, 5, 7, 9: {{Cl|PRINT}} "Odd values under 10 will be shown." @@ -73,8 +52,8 @@ a = 100 :* [[CASE IS]] is used when we need to compare the value to a conditional expression range such as a value is "=" equal to, "<" less than, ">" greater than, "<>" not equal to or [[NOT]] a value. -:* A [[CASE]] range can be specified (in the example; 50 {{KW|TO}} 150) if needed. -<center>''Note:'' A {{KW|SELECT CASE}} block has to end with [[END SELECT]].</center> +:* A [[CASE]] range can be specified (in the example; 50 [[TO]] 150) if needed. +<center>''Note:'' A [[SELECT CASE]] block has to end with [[END SELECT]].</center> {{PageSeeAlso}} diff --git a/internal/help/CASE_ELSE.txt b/internal/help/CASE_ELSE.txt index 6f260542c..103e32ca6 100644 --- a/internal/help/CASE_ELSE.txt +++ b/internal/help/CASE_ELSE.txt @@ -1,11 +1,11 @@ -{{KW|CASE ELSE}} is used in a {{KW|SELECT CASE}} procedure as an alternative if no other {{KW|CASE}} statements are true. +#REDIRECT [[SELECT CASE#allCASES]] + +[[CASE ELSE]] is used in a [[SELECT CASE]] procedure as an alternative if no other [[CASE]] statements are true. {{PageDescription}} - -* CASE ELSE should be listed at the bottom of the case list as it will supercede any case statements after it. -* Use it as a "safety net" or as an alternative for ALL values not covered in the {{KW|CASE}} statements. - +* [[CASE ELSE]] should be listed at the bottom of the case list as it will supersede any case statements after it. +* Use it as a "safety net" or as an alternative for all values not covered in the [[CASE]] statements. {{PageExamples}} @@ -29,6 +29,7 @@ a is 100 {{OutputEnd}} + ''Example 2:'' {{CodeStart}} @@ -54,9 +55,8 @@ a is something other than 10, 20 and 30 {{PageSeeAlso}} - -*{{KW|SELECT CASE}} -*{{KW|IF...THEN}}, {{KW|ELSE}} +*[[SELECT CASE]] +*[[IF...THEN]], [[ELSE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CASE_IS.txt b/internal/help/CASE_IS.txt index 870385fd8..3439adae3 100644 --- a/internal/help/CASE_IS.txt +++ b/internal/help/CASE_IS.txt @@ -1,3 +1,5 @@ +#REDIRECT [[SELECT CASE#allCASES]] + [[CASE IS]] can be used in a [[SELECT CASE]] routine where you need to use relational conditional expressions. @@ -6,9 +8,12 @@ {{PageDescription}} +* [[AND (boolean)|AND]] can be used to add extra conditions to a [[CASE IS]] statement evaluation. +* [[OR (boolean)|OR]] can be used to add alternate conditions to a [[CASE IS]] statement evaluation. +* Parenthesis are allowed in [[CASE IS]] statements to clarify an evaluation. * [[CASE IS]] > 100 uses the greater than expression. * [[CASE IS]] <= 100 uses the less than or equal to expression. -* [[CASE IS]] <> 100 uses the not equal to expression(same as {{KW|NOT}} 100). +* [[CASE IS]] <> 100 uses the not equal to expression(same as [[NOT]] 100). {{Template:RelationalTable}} diff --git a/internal/help/CDBL.txt b/internal/help/CDBL.txt index b02c55d57..8cf8e7903 100644 --- a/internal/help/CDBL.txt +++ b/internal/help/CDBL.txt @@ -1,20 +1,21 @@ -{{KW|CDBL}} converts a value to the closest {{KW|DOUBLE}}-precision value. +[[CDBL]] converts a value to the closest [[DOUBLE]]-precision value. {{PageSyntax}} -:: doublevalue = '''CDBL('''''expression''''')''' +: {{Parameter|doubleValue#}} = [[CDBL]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[TYPE]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} * Rounds to the closest [[DOUBLE]] floating decimal point value. -* Also can be used to define a value as {{KW|DOUBLE}}-precision up to 15 decimals. +* Also can be used to define a value as [[DOUBLE]]-precision up to 15 decimals. +{{PageExamples}} ''Example:'' Prints a double-precision version of the single-precision value stored in the variable named A. {{CodeStart}} A = 454.67 diff --git a/internal/help/CDECL.txt b/internal/help/CDECL.txt index e959a3653..800a24bc4 100644 --- a/internal/help/CDECL.txt +++ b/internal/help/CDECL.txt @@ -1,17 +1,23 @@ -CDECL is used to indicate that the external procedure uses the C-language argument order. +#REDIRECT [[DECLARE (non-BASIC statement)]] + +'''This page is maintained for historic purposes. The keyword is not supported in QB64.''' + +---- + +[[CDECL]] is used to indicate that the external procedure uses the C-language argument order. {{PageSyntax}} -:: [[DECLARE]] {[[SUB]]|[[FUNCTION]]} name ['''CDECL'''] [ [[ALIAS]] "aliasname"] [([parameterlist])] +: [[DECLARE]] {[[SUB]]|[[FUNCTION]]} name ['''CDECL'''] [ [[ALIAS]] "aliasname"] [([parameterlist])] -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * QuickBASIC will pass the arguments in the argument list from right to left instead of left to right which is the BASIC convention. {{PageSeeAlso}} -*{{KW|CALL}}, {{KW|CALLS}} -*{{KW|DECLARE (non-BASIC statement)}} +*[[CALL]], [[CALLS]] +*[[DECLARE (non-BASIC statement)]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CHAIN.txt b/internal/help/CHAIN.txt index a2e82b22c..6cdf4601b 100644 --- a/internal/help/CHAIN.txt +++ b/internal/help/CHAIN.txt @@ -1,34 +1,39 @@ -'''CHAIN''' is used to change seamlessly from one module to another one in a program. Available in Quickbasic 4.0 and up. +[[CHAIN]] is used to change seamlessly from one module to another one in a program. + + +==Legacy support== +* The multi-modular technique goes back to when QBasic and QuickBASIC had module size constraints. In QB64 [[CHAIN]] has been implemented so that that older code can still be compiled, though '''it is advisable to use single modules for a single project (not counting [[$INCLUDE]] libraries), for ease of sharing and also because the module size constraints no longer exist.''' {{PageSyntax}} -::: '''CHAIN {{Parameter|ModuleName$}}''' - +: [[CHAIN]] {{Parameter|moduleName$}} {{Parameters}} -* The ''module'' name is a variable or a literal [[STRING]] value in quotation marks with the optional EXE or BAS file name extension. +* {{Parameter|moduleName$}} is a variable or a literal [[STRING]] value in quotation marks with the optional EXE or BAS file name extension. -''Usage:'' -* CHAIN requires that both the invoking and called modules are of either .BAS or .EXE file types! +{{PageDescription}} +* CHAIN requires that both the invoking and called modules are of either .BAS or .EXE file types. * In Windows, '''QB64''' will automatically compile a CHAIN referenced BAS file if there is no EXE file found. * CHAIN looks for a file extension that is the same as the invoking module's extension. -* The module's filename extension is NOT required. To save editing at compile time just omit the extensions in the calls. -* To pass data from one module to the other use [[COMMON SHARED]]. The COMMON list should match [[type]]s and names! -* Compiled EXE files MUST include BRUN45.EXE in QuickBasic 4.5 when CHAIN is used with [[COMMON SHARED]]. -* Module screen modes will not change unless that is desired. '''QB64 currently does not retain the [[SCREEN]] mode!''' -* Use when modules are too large to compile(Over 100K approx.). Split the modules up. NOT necessary with '''QB64'''! +* The module's filename extension is not required. To save editing at compile time just omit the extensions in the calls. +* To pass data from one module to the other use [[COMMON SHARED]]. The COMMON list should match [[type]]s and names. +* '''QB64 does not retain the [[SCREEN]] mode like QBasic did.''' * Variable data can be passed in files instead of using [[COMMON SHARED]] values. '''QB64''' uses files to pass [[COMMON]] lists. -* '''NOTE: CHAIN is no longer required using QB64 as it can run larger modules: [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Not currently available in Linux or Mac operating systems!]]''' +* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Not available in Linux or macOS]]'''. -''Example:'' CHAIN looks for same file type extension as program module (BAS or EXE) in QB 4.5. +''QBasic/QuickBASIC:'' +* Compiled EXE files had to include BRUN45.EXE in QuickBASIC 4.5 when CHAIN was used with [[COMMON SHARED]]. + + +{{PageExamples}} +''Example:'' CHAIN looks for same file type extension as program module (BAS or EXE). {{CodeStart}} '' '' {{Cl|CHAIN}} "Level1" '' '' {{CodeEnd}} - -''Explanation:'' The file referred to is "Level1.BAS" if the program module using the call is a BAS file. If the program was compiled, it would look for "Level1.EXE". QuickBasic4.5 requires that [[COMMON]] or [[COMMON SHARED]] data sharing programs be compiled with BRUN45.EXE being included with the program package(the EXE file will also be larger). '''QB64''' does not have that requirement as it creates data files to pass common data information. +''Explanation:'' The file referred to is "Level1.BAS" if the program module using the call is a BAS file. If the program was compiled, it would look for "Level1.EXE". {{PageSeeAlso}} diff --git a/internal/help/CHDIR.txt b/internal/help/CHDIR.txt index b8577c15a..dc7f5db46 100644 --- a/internal/help/CHDIR.txt +++ b/internal/help/CHDIR.txt @@ -1,39 +1,33 @@ -The {{KW|CHDIR}} statement changes the program's location from one working directory to another by specifying a literal or variable [[STRING]] path. +The [[CHDIR]] statement changes the program's location from one working directory to another by specifying a literal or variable [[STRING]] path. {{PageSyntax}} -:{{KW|CHDIR}} {{Parameter|path$}} +:[[CHDIR]] {{Parameter|path$}} {{PageDescription}} -* Path directory names must use the 8 letter maximum DOS name in Qbasic. '''QB64''' can use long path names. * {{Parameter|path$}} is the new directory path the program will work in. -* {{Parameter|path$}} can be an absolute(starting from root drive) or relative(starting from the present program location) path. +* {{Parameter|path$}} can be an absolute path (starting from the root folder) or relative path (starting from the current program location). * If {{Parameter|path$}} specifies a non-existing path, a [[ERROR Codes|"Path not found"]] error will occur. -* '''A QB64 [[SHELL]] statement cannot currently use "CD " or "CHDIR " + path$ to change the directory using DOS.''' -* '''WARNING: The new program path location must have the relevant files the program requires to run properly!''' +* '''A QB64 [[SHELL]] statement cannot use "CD " or "CHDIR " + path$ to change directories.''' -''Example 1:'' The following code is MS DOS and Windows-specific: +{{PageExamples}} +''Example 1:'' The following code is Windows-specific: {{CodeStart}} '' '' {{Cl|CHDIR}} "C:\" 'change to the root drive C (absolute path) - {{Cl|CHDIR}} "DOCUME~1" 'change to "C:\Documents and Settings" from root drive (relative path) - {{Cl|CHDIR}} "..\" 'change back to previous folder one up '' '' {{CodeEnd}} -:''Details:'' There is an 8 letter path folder name limit in Qbasic. For folder names longer than eight characters use the first 6 letters(remove spaces) with a tilde(~) and a number(normally 1). '''QB64''' can use long or short(8.3 notation) file and path names! ''Remember that the program location has actually been moved so files in the original location must be accessed using a path.'' +:''Details:'' '''QB64''' can use long or short (8.3 notation) file and path names. ''Example 2:'' Using the Windows API to find the current program's name and root path. The PATH$ is a shared function value. {{CodeStart}} '' '' {{Cl|_TITLE}} "My program" - {{Cl|PRINT}} TITLE$ - {{Cl|PRINT}} PATH$ - {{Cl|FUNCTION}} TITLE$ ''=== SHOW CURRENT PROGRAM {{Cl|SHARED}} PATH$ 'optional path information shared with main module only {{Cl|DECLARE LIBRARY}} 'Directory Information using KERNEL32 provided by Dav @@ -56,14 +50,14 @@ Result = GetModuleFileNameA(0, FileName$, {{Cl|LEN}}(FileName$)) '0 designates {{Cl|END IF}} {{Cl|END FUNCTION}} '' '' {{CodeEnd}} -: '''Note:''' The program's [[_TITLE]] name may be different from the actual program module's file name returned by Windows! +: '''Note:''' The program's [[_TITLE]] name may be different from the actual program module's file name returned by Windows. {{PageSeeAlso}} * [[SHELL]], [[FILES]] * [[MKDIR]], [[RMDIR]] * [[DOS]], [[Batch Files]] -* [[C_Libraries#Console_Window|C Console Library]] +* [[$CONSOLE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CHR$.txt b/internal/help/CHR$.txt index 19422308f..c50606aa1 100644 --- a/internal/help/CHR$.txt +++ b/internal/help/CHR$.txt @@ -1,14 +1,14 @@ -The {{KW|CHR$}} function returns the character associated with a certain [[ASCII|character code]] as a {{KW|STRING}}. +The [[CHR$]] function returns the character associated with a certain [[ASCII|character code]] as a [[STRING]]. {{PageSyntax}} -:''result$'' = {{KW|CHR$}}({{Parameter|code%}}) +:{{Parameter|result$}} = [[CHR$]]({{Parameter|code%}}) {{PageDescription}} -* Valid ASCII code numbers range from 0 to 255. -* The character code of a character can be found using {{KW|ASC}}. -* Some control codes below 32 will not {{KW|PRINT}} or will move the screen cursor. +* Valid ASCII {{Parameter|code%}} numbers range from 0 to 255. +* The character code of a character can be found using [[ASC]]. +* Some control codes below 32 will not [[PRINT]] or will move the screen cursor, unless [[_CONTROLCHR|_CONTROLCHR OFF]] is used. {{PageExamples}} @@ -36,7 +36,7 @@ This text uses "quotation marks" that could have caused a syntax error {{OutputEnd}} -''Example 3:'' Using {{KW|ASC}} and {{KW|CHR$}} to '''Encrypt''' a text file size up to 32K bytes +''Example 3:'' Using [[ASC]] and [[CHR$]] to ''encrypt'' a text file size up to 32K bytes {{CodeStart}}{{Cl|OPEN}} FileName$ {{Cl|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #1 ' FileName to be encrypted {{Cl|IF...THEN|IF}} {{Cl|LOF}}(1) <= 32000 {{Cl|THEN}} Text$ = {{Cl|INPUT$}}({{Cl|LOF}}(1), 1) ' get Text as one string {{Cl|CLOSE}} #1 @@ -53,9 +53,7 @@ Send$ = "" ' clear value {{Cl|PRINT (file statement)|PRINT}} #1, Send$ ' Text as one string {{Cl|CLOSE}} #1 {{CodeEnd}} - -::'''Warning: Above routine will change ORIGINAL text file to be unreadable!''' -::::''Use a second Filename to preserve the original file!'' +:''Warning: The routine above will change an original text file to be unreadable. Use a second file name to preserve the original file.'' ''Example 4:'' '''Decrypting''' the above encrypted text file (32K byte file size limit). @@ -76,12 +74,12 @@ Send$ = "" {{Cl|CLOSE}} #1 '' '' {{CodeEnd}} {{small|Code by Ted Weissgerber}} -:''Explanation:'' Examples 3 and 4 Encrypt and Decrypt a file up to 32 thousand bytes only! [[INPUT$]] can only get strings less than 32767 characters. The upper and lower case letter characters are the only ones altered, but the encryption and decryption rely on the fact that MOST text files do not use the code characters above 193. You could alter any character from ASCII 32 to 125 without problems using the 130 adder. '''NO [[ASCII]] code above 255 is allowed!''' DON'T alter the codes below code 32 as they are Control characters. Specifically, characters 13 and 10 (CrLf) may be used for line returns in text files. +:''Explanation:'' Examples 3 and 4 encrypt and decrypt a file up to 32 thousand bytes. [[INPUT$]] can only get strings less than 32767 characters. The upper and lower case letter characters are the only ones altered, but the encryption and decryption rely on the fact that most text files do not use the code characters above 193. You could alter any character from ASCII 32 to 125 without problems using the 130 adder. No [[ASCII]] code above 255 is allowed. Don't alter the codes below code 32 as they are control characters. Specifically, characters 13 and 10 (CrLf) may be used for line returns in text files. {{PageSeeAlso}} -* {{KW|ASC}}, {{KW|ASC (statement)}}(QB64) -* {{KW|INKEY$}} +* [[ASC]], [[ASC (statement)]] +* [[INKEY$]] * [[ASCII|ASCII character codes]] diff --git a/internal/help/CINT.txt b/internal/help/CINT.txt index adf4d8ef2..0769c9ab1 100644 --- a/internal/help/CINT.txt +++ b/internal/help/CINT.txt @@ -1,35 +1,35 @@ -The {{KW|CINT}} function rounds decimal point numbers up or down to the nearest {{KW|INTEGER}} value. +The [[CINT]] function rounds decimal point numbers up or down to the nearest [[INTEGER]] value. {{PageSyntax}} -:: value = '''CINT('''''expression''''')''' +: {{Parameter|value%}} = [[CINT]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[TYPE]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} -* Values greater than .5 are rounded up. Values lower than .5 are rounded down just like "bankers rounding". -* Half(.5) [[SINGLE]] values are rounded to the nearest EVEN integer value whether it is up or down. -* ''Warning:'' Since {{KW|CINT}} is used for integer values, the input values cannot exceed 32767 to -32768! -* Use {{KW|CLNG}} for {{KW|LONG}} integer values exceeding Integer limitations. -* Note: When decimal point values are given to Basic functions requiring [[INTEGER]]s the value will be CINTed. +* Values greater than .5 are rounded up. Values lower than .5 are rounded down. +* ''Warning:'' Since [[CINT]] is used for integer values, the input values cannot exceed 32767 to -32768! +* Use [[CLNG]] for [[LONG]] integer values exceeding [[INTEGER]] limitations. +* Note: When decimal point values are given to BASIC functions requiring [[INTEGER]]s the value will be [[CINT]]ed. -''Example:'' Shows how CINT rounds values up or down as in bankers rounding. +{{PageExamples}} +''Example:'' Shows how CINT rounds values up or down as in "bankers' rounding". {{CodeStart}} '' '' a% = {{Cl|CINT}}(1.49): b% = {{Cl|CINT}}(1.50): c = 11.5 {{Cl|COLOR}} c: {{Cl|PRINT}} a%, b%, c '' '' {{CodeEnd}} {{OutputStart}}{{text|1 2 11.5|red}} {{OutputEnd}} -:''Note:'' Qbasic functions requiring [[INTEGER]] values such as text or graphic coordinates and {{KW|COLOR}} will be rounded like {{KW|CINT}}. Half values are rounded to the nearest even integer value. {{PageSeeAlso}} -* {{KW|CLNG}}, {{KW|CSNG}}, {{KW|CDBL}} -* {{KW|INT}}, {{KW|FIX}}, {{KW|_ROUND}} +* [[_ROUND]], [[_CEIL]] +* [[CLNG]], [[CSNG]], [[CDBL]] +* [[INT]], [[FIX]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CIRCLE.txt b/internal/help/CIRCLE.txt index ec568bac2..c8aeffee5 100644 --- a/internal/help/CIRCLE.txt +++ b/internal/help/CIRCLE.txt @@ -1,102 +1,29 @@ -The {{KW|CIRCLE}} statement is used in graphics {{KW|SCREEN (statement)|SCREEN}} modes to create circles, arcs or ellipses. - +The [[CIRCLE]] statement is used in graphic [[SCREEN (statement)|SCREEN]] modes to create circles, arcs or ellipses. {{PageSyntax}} -: '''CIRCLE''' [{{KW|STEP}}]'''('''{{Parameter|Column}}''',''' {{Parameter|Row}}'''),''' {{Parameter|radius%}}''',''' [{{Parameter|colour%}}][, {{Parameter|startRadian!}}, {{Parameter|stopRadian!}}] [, {{Parameter|aspect!}}] +: [[CIRCLE]] [{{KW|STEP}}]'''('''{{Parameter|column}}''',''' {{Parameter|row}}'''),''' {{Parameter|radius%}}''',''' [{{Parameter|drawColor%}}][, {{Parameter|startRadian!}}, {{Parameter|stopRadian!}}] [, {{Parameter|aspect!}}] {{Parameters}} * Can use [[STEP]] for relative coordinate moves from the previous graphic coordinates. * Coordinates designate the center position of the circle. Can be partially drawn offscreen. * {{Parameter|radius%}} is an [[INTEGER]] value for half of the total circle diameter. -* {{Parameter|colour%}} is any available color attribute in the {{KW|SCREEN (statement)|SCREEN}} mode used. -* {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} can be any {{KW|SINGLE}} value from 0 to 2 * pi to create partial circles or ellipses. -* ''aspect!'' [[SINGLE]] values of 0 to 1 affect the vertical height and values over 1 affect the horizontal width of an ellipse. Aspect = 1 is a normal circle. +* {{Parameter|drawColor%}} is any available color attribute in the [[SCREEN (statement)|SCREEN]] mode used. +* {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} can be any [[SINGLE]] value from 0 to 2 * &pi; to create partial circles or ellipses. +* {{Parameter|aspect!}} [[SINGLE]] values of 0 to 1 affect the vertical height and values over 1 affect the horizontal width of an ellipse. Aspect = 1 is a normal circle. -''Usage:'' -* When using {{Parameter|aspect!}} the {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} commas MUST be included even if not used. -* Radians move in a counter clockwise direction from 0 to 2 * Pi. Zero and 2 * Pi are the same circle radian at 3 o'clock. +{{PageDescription}} +* When using {{Parameter|aspect!}} the {{Parameter|startRadian!}} and {{Parameter|stopRadian!}} commas must be included even if not used. +* Radians move in a counter clockwise direction from 0 to 2 * &pi;. Zero and 2 * &pi; are the same circle radian at 3 o'clock. * Negative radian values can be used to draw lines from the end of an arc or partial ellipse to the circle center. -* Commas after the {{Parameter|colour%}} parameter are not required when creating a normal circle. Color can also be omitted. -* The QB64 and QB graphic cursor is set to the center of the program window on program start. -* '''CIRCLE can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only!''' - - -<center>'''Circle.BI Include file or [[SUB]] to use when using [[PAINT]] with pie charts or arc slices:'''</center> -{{TextStart}} 'CIRCLE.BI -'** -'** QB64 temporary replacement CIRCLE command. -'** -'** The CIRCLE command in QB64 has a few bugs listed below: -'** -'** - radian end points are not calculate properly when creating arcs -'** - center line to radian end points do not close properly due to previous bug listed -'** -'** This circle command replacement works very similiarly to the native CIRCLE command: -'** -'** SYNTAX: CIRCLES x%, y%, radius!, color~&, start_radian!, end_radian!, aspect_ratio! -'** -'** x% - center X coordinate of circle -'** y% - center Y coordinate of circle -'** radius! - the radius of the circle -'** color~& - the circle's color -'** start_radian! - the radian on circle curcunference to begin drawing at -'** end_radian! - the radian on circle circumference to end drawing at -'** aspect_ratio! - the aspect ratio of the circle -'** -'** '''NOTE: unlike the native CIRCLE command, all arguments MUST be supplied.''' For example, -'** with the native command this will draw a perfect circle with the default color, -'** start radian, end radian and aspect ratio: -'** -'** CIRCLE (319, 239), 100 -'** -'** To do the same thing with this replacement command you must supply everything: -'** -'** CIRCLES 319, 239, 100, _RGB32(255, 255, 255), 0, 0, 0 -'** -'** ACKNOWLEGEMENTS: The FOR/NEXT step formula was was written by Codeguy for Unseen -'** Machine's Visual library EllipseXS command. Specifically: -'** MinStep! = 1 / (2 * 3.1415926535 * Radius!) -'** -'** -'** Includes performance tweaks made by SMcNeill on 02/02/13 - specifically removing a few redundant * -1 -'** statements and converting the FOR/NEXT loop to a DO loop for a ~3% increase in performance. -'** -'** Corrected bug in which variables being passed in were being modified and passed back - 02/02/13 -'** -'''SUB CIRCLES (cx%, cy%, r!, c~&, s!, e!, a!)''' -DIM s%, e%, nx%, ny%, xr!, yr!, st!, en!, asp! ' local variables used - -st! = s! ' copy start radian to local variable -en! = e! ' copy end radian to local variable -asp! = a! ' copy aspect ratio to local variable -IF asp! <= 0 THEN asp! = 1 ' keep aspect ratio between 0 and 4 -IF asp! > 4 THEN asp! = 4 -IF asp! < 1 THEN xr! = r! * asp! * 4 ELSE xr! = r! ' calculate x/y radius based on aspect ratio -IF asp! > 1 THEN yr! = r! * asp! ELSE yr! = r! -IF st! < 0 THEN s% = -1: st! = -st! ' remember if line needs drawn from center to start radian -IF en! < 0 THEN e% = -1: en! = -en! ' remember if line needs drawn from center to end radian -IF s% THEN ' draw line from center to start radian? - nx% = cx% + xr! * COS(st!) ' yes, compute starting point on circle's circumference - ny% = cy% + yr! * -SIN(st!) - LINE (cx%, cy%)-(nx%, ny%), c~& ' draw line from center to radian -END IF -IF en! <= st! THEN en! = en! + 6.2831852 ' come back around to proper location (draw counterclockwise) -stepp! = 0.159154945806 / r! -c! = st! ' cycle from start radian to end radian -DO - nx% = cx% + xr! * COS(c!) ' compute next point on circle's circumfrerence - ny% = cy% + yr! * -SIN(c!) - PSET (nx%, ny%), c~& ' draw the point - c! = c! + stepp! -LOOP UNTIL c! >= en! -IF e% THEN LINE -(cx%, cy%), c~& ' draw line from center to end radian if needed -'''END SUB''' -{{TextEnd}} +* Commas after the {{Parameter|drawColor%}} parameter are not required when creating a normal circle. {{Parameter|drawColor%}} can also be omitted to use the last color used in a draw statement. +* The graphic cursor is set to the center of the program window on program start for [[STEP]] relative coordinates. +* '''CIRCLE can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only.''' +{{PageExamples}} ''Example 1:'' Finding when the mouse is inside of a circular area: {{CodeStart}} '' '' {{Cl|SCREEN}} 12 @@ -118,7 +45,7 @@ DO ''Example 2:'' Program illustrates how the CIRCLE command using a negative radian value can be used to create the hands of a clock. {{CodeStart}} '' '' -{{Cl|CONST}} PI = 3.141593 'The mathematical value of PI to six places +{{Cl|CONST}} PI = 3.141593 'The mathematical value of PI to six places. You can also use QB64's native _PI. {{Cl|DIM}} clock(60) 'A dimensioned array to hold 60 radian points clockcount% = 15 'A counter to keep track of the radians @@ -206,13 +133,13 @@ previoushour% = hours% 'hold current hour for later use {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" 'stop program if user presses a key '' '' {{CodeEnd}} -{{small|Circle clock - by Terry Ritchie 11/04/06}} +{{small|code by Terry Ritchie}} {{PageSeeAlso}} * [[STEP]], [[DRAW]] * [[LINE]], [[PSET]], [[PRESET]] * [[SCREEN]], [[SCREEN (function)]] - +* [[Alternative circle routine]] {{text|(member-contributed program)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CLEAR.txt b/internal/help/CLEAR.txt index 69db57fef..05e363d1e 100644 --- a/internal/help/CLEAR.txt +++ b/internal/help/CLEAR.txt @@ -1,18 +1,19 @@ -The ''CLEAR''' statement clears all variable and array element values in a program. It does not affect constant values! +The [[CLEAR]] statement clears all variable and array element values in a program. -''Syntax:'' '''CLEAR''' [, ''stacksize&'' , ''stackspace&''] +{{PageSyntax}} +: [[CLEAR]] [, {{Parameter|ignored&}} , {{Parameter|ignored&}}] {{PageDescription}} -* Optional ''stacksize'' parameter was not required as Qbasic managed that. '''All parameters and commas are ignored by QB64!''' -* The ''stackspace'' parameter sets the stack space to be added to the stack. Two commas kept Qbasic compatible with BASICA. -* Normally used to clear all program variable and [[Arrays|array]] values where numerical values become zero and string values become null. +* All parameters are optional and ignored by '''QB64'''. +* Normally used to clear all program variable and [[Arrays|array]] values where numerical values become zero and string values become empty (""). * It does not clear [[CONST|constant]] values. -* Closes all opened files also. -* [[$DYNAMIC]] or [[REDIM]] arrays will need to be [[REDIM|re-dimensioned]] or an [[ERROR Codes|error]] will occur when referenced because it was removed. +* Closes all opened files. +* [[$DYNAMIC]] or [[REDIM]] arrays will need to be [[REDIM|redimensioned]] or an [[ERROR Codes|error]] will occur when referenced because they are removed. +{{PageExamples}} ''Example:'' Using CLEAR to clear array elements from [[STATIC|static]] arrays or arrays created using [[DIM]]. {{CodeStart}} '' '' {{Cl|CLS}} @@ -29,9 +30,8 @@ array(5) = 23 {{PageSeeAlso}} -* [[ERASE]] {{text|(array names only)}} -* [[REDIM]] {{text|(array sizes only)}} -* [[_PRESERVE]] {{text|(REDIM arrays only)}} +* [[ERASE]] +* [[REDIM]], [[_PRESERVE]] * [[Arrays]], [[&B|_BIT arrays]] diff --git a/internal/help/CLNG.txt b/internal/help/CLNG.txt index f29b355d4..33ab770a2 100644 --- a/internal/help/CLNG.txt +++ b/internal/help/CLNG.txt @@ -1,23 +1,22 @@ -The {{KW|CLNG}} function rounds decimal point numbers up or down to the nearest {{KW|LONG}} integer value. +The [[CLNG]] function rounds decimal point numbers up or down to the nearest [[LONG]] integer value. {{PageSyntax}} -:: value = '''CLNG('''''expression''''')''' +: {{Parameter|value&}} = [[CLNG]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[TYPE]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} * Used when integer values exceed 32767 or are less than -32768. -* Values greater than .5 are rounded up; .5 or lower are rounded down like "bankers rounding". -* CLNG can return normal {{KW|INTEGER}} values under 32768 also. -* Use it when a number could exceed normal {{KW|INTEGER}} number limits. +* Values greater than .5 are rounded up; .5 or lower are rounded down. +* CLNG can return normal [[INTEGER]] values under 32768 too. +* Use it when a number could exceed normal [[INTEGER]] number limits. {{PageExamples}} - {{CodeStart}} a& = {{Cl|CLNG}}(2345678.51) {{Cl|PRINT}} diff --git a/internal/help/CLOSE.txt b/internal/help/CLOSE.txt index 587096892..994d1f931 100644 --- a/internal/help/CLOSE.txt +++ b/internal/help/CLOSE.txt @@ -1,22 +1,22 @@ -{{KW|CLOSE}} closes an opened file or port using the number(s) assigned in an {{KW|OPEN}} statement. +[[CLOSE]] closes an open file or port using the number(s) assigned in an [[OPEN]] statement. {{PageSyntax}} -::: '''CLOSE''' [''filenumber''[, ...]] +: [[CLOSE]] [{{Parameter|fileNumber}}[, ...]] -''[[Parameters]]:'' -* ''filenumber'' indicates the file or list of file numbers to close. When not designated all files are closed. +{{Parameters}} +* {{Parameter|fileNumber}} indicates the file or list of file numbers to close. When not specified, all open files are closed. -''Usage:'' -* A file MUST be closed when changing to another file mode. -* CLOSE files when they are no longer needed to save memory. +{{PageDescription}} +* A file must be closed when changing to another file mode. +* [[CLOSE]] files when they are no longer needed, in order to save memory. * Files cannot be opened in the same [[OPEN]] mode using another number until the first one is closed. * Use holding variables for each file number returned by [[FREEFILE]] so that the file reference is known. * Will not return an error if a filenumber is already closed or was never opened. It does not verify that a file was closed. -* [[CLEAR]] will also close all open files. -* CLOSE can also be used to close an open TCP/IP connection using a handle returned by '''QB64'''. +* [[CLEAR]] can be used to close all open files. +* [[CLOSE]] can also be used to close an open TCP/IP connection using a handle returned by '''QB64'''. {{PageSeeAlso}} diff --git a/internal/help/CLS.txt b/internal/help/CLS.txt index 243c0a179..57aebe6da 100644 --- a/internal/help/CLS.txt +++ b/internal/help/CLS.txt @@ -1,8 +1,8 @@ -The {{KW|CLS}} statement clears the current write page. +The [[CLS]] statement clears the [[_DEST|current write page]]. {{PageSyntax}} -::: '''CLS''' [{{Parameter|method%}}] [, {{Parameter|BGcolor&}}] +: [[CLS]] [{{Parameter|method%}}] [, {{Parameter|bgColor&}}] {{Parameters}} @@ -11,19 +11,20 @@ The {{KW|CLS}} statement clears the current write page. ** CLS 0 - Clears the entire page of text and graphics. Print cursor is moved to row 1 at column 1. ** CLS 1 - Clears only the graphics view port. Has no effect for text mode. ** CLS 2 - Clears only the text view port. The print cursor is moved to the top row of the text view port at column 1. -* The {{Parameter|BGcolor&}} specifies the color attribute or palette index to use when clearing the screen in '''QB64 only'''. +* The {{Parameter|bgColor&}} specifies the color attribute or palette index to use when clearing the screen in '''QB64'''. -''Usage:'' -** In legacy [[SCREEN]] modes {{Parameter|BGcolor&}} specifies the color attribute of the background. -** For 32-bit graphics mode, {{Parameter|BGcolor&}} specifies the [[_RGB]] or [[_RGBA]] color to use. -* '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' -: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opague. -** If not specified, {{Parameter|BGcolor&}} is assumed to be the current background color. 32 bit backgrounds will change to opaque! -** If {{Parameter|BGColor&}} is not a valid attribute, an [[ERROR Codes|illegal function call]] error will occur! +{{PageDescription}} +* In legacy [[SCREEN]] modes {{Parameter|bgColor&}} specifies the color attribute of the background. +* For 32-bit graphics mode, {{Parameter|bgColor&}} specifies the [[_RGB]] or [[_RGBA]] color to use. +* '''32-bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +** Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque. +* If not specified, {{Parameter|bgColor&}} is assumed to be the current background color. 32-bit backgrounds will change to opaque. +* If {{Parameter|bgColor&}} is not a valid attribute, an [[ERROR Codes|illegal function call]] error will occur. * Use [[_PRINTMODE]] to allow the background colors to be visible through the text or the text background. +{{PageExamples}} ''Example 1:'' Printing black text on a white background in QB64. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 @@ -39,20 +40,18 @@ K$ = {{Cl|INPUT$}}(1 {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) {{Cl|CLS}} , {{Cl|_RGB}}(0, 255, 0) -i = {{Cl|_LOADIMAGE}}('''"QB64.PNG"''') 'see note below examples to get the image -{{Cl|_PUTIMAGE}} (0, 0), i ' places image at upper left corner of window w/o stretching it +i = {{Cl|_LOADIMAGE}}('''"qb64_trans.png"''') 'see note below examples to get the image +{{Cl|_PUTIMAGE}} (0, 0), i 'places image at upper left corner of window w/o stretching it '' '' {{CodeEnd}} '' '' -: ''Explanation:'' When QB64 loads a 256 color .PNG file containing a transparent color, that color will be treated as transparent when _PUTIMAGE is used to put it onto another image. So actually, you can use a 256-color .PNG file containing transparency information in a 256 color screen mode in QB64. [[CLS]] sets the [[_CLEARCOLOR]] setting using [[_RGB]]. - -<center>''Note:'' The ''QB64.PNG'' Bee image used can be copied from the top of the [http://www.qb64.net/forum/index.php Main Forum Page]</center> +: ''Explanation:'' When QB64 loads a .PNG file containing a transparent color, that color will be properly treated as transparent when _PUTIMAGE is used to put it onto another image. You can use a .PNG file containing transparency information in a 256-color screen mode in QB64. [[CLS]] sets the [[_CLEARCOLOR]] setting using [[_RGB]]. +: ''Note:'' The ''qb64_trans.png'' bee image used can be downloaded from [http://www.qb64.net/qb64_trans.png qb64_trans.png] {{PageSeeAlso}} - * [[SCREEN]] -* [[_RGB]], [[_RGBA]] +* [[_RGB]], [[_RGBA]], [[_RGB32]], [[_RGBA32]] * [[VIEW PRINT]], [[VIEW]] * [[_CLEARCOLOR]] diff --git a/internal/help/COLOR.txt b/internal/help/COLOR.txt index 62f748642..06acc20a9 100644 --- a/internal/help/COLOR.txt +++ b/internal/help/COLOR.txt @@ -1,66 +1,45 @@ -The {{KW|COLOR}} statement is used to change the color of text and background in some [[SCREEN]] modes. - -{| align="Right" - | __TOC__ - |} - +The [[COLOR]] statement is used to change the foreground and background colors for printing text. {{PageSyntax}} -:{{KW|COLOR}} [{{Parameter|foreground%}}][, {{Parameter|background%}}] +: [[COLOR]] [{{Parameter|foreground&}}][, {{Parameter|background&}}] - -* ''Background'' colors are available in SCREEN modes 0, 1, 7, 8 and 9 only. +{{PageDescription}} +* {{Parameter|background&}} colors are available in all QB64 color SCREEN modes. * [[SCREEN]] mode 10 has only 3 white foreground attributes including flashing. -* [[SCREEN]] modes 12 and 13 can use the foreground parameter only! Background color 0 can be changed using [[OUT]]. -* '''[[SCREEN]] modes 2 and 11 cannot use the COLOR keyword as they are monochrome with white foreground!''' -* An [[ERROR Codes|illegal function error]] will occur if a background color is used in other screen modes! -* To change the ''background'' color only, use a comma and the color. EX: COLOR ,background% -* In '''GW-Basic''' a third border color parameter could be used while in SCREEN 0. The third argument can still be passed in SCREEN 0. Using the third argument in other screen modes will give "Illegal Function Call" Error or will '''crash''' without error in 32-bit screens. +* To change the {{Parameter|background&}} color only, use a comma and the desired color. Ex: [[COLOR]] , {{Parameter|background&}} +* Graphic drawing statements like [[PSET]], [[PRESET]], [[LINE]], etc, also use the colors set by the [[COLOR]] statement if no color is passed when they are called. ==Screen Mode Attributes== - -* '''SCREEN 0''' ''background'' colors 0 to 7 can be changed each text character without affecting other text. Use {{KW|CLS}} after a background color statement to create a fullscreen background color. 64 [[DAC]] hues with 16 high intensity blinking foreground (16 to 31) color attributes. QBasic windows will not flash in a window in NT, XP, VISTA or 7 (will flash in '''QB64'''). See example 7 below for more SCREEN 0 background colors. - +* '''SCREEN 0''' {{Parameter|background&}} colors 0 to 7 can be changed each text character without affecting other text. Use [[CLS]] after a background color statement to create a fullscreen background color. 64 [[DAC]] hues with 16 high intensity blinking foreground (16 to 31) color attributes. See [[_BLINK]]. +** See example 7 below for more SCREEN 0 background colors. * '''SCREEN 1''' has '''4 background color attributes''': 0 = black, 1 = blue, 2 = green, 3 = grey. White foreground color only. - -* '''SCREEN 2''' is '''monochrome''' with white forecolor and black background. '''Cannot use the COLOR statement!''' - -* '''SCREEN 7''' can use 16 ([[DAC]]) colors with background colors. RGB settings can be changed in colors 0 to 7 using {{KW|OUT}}. - +* '''SCREEN 2''' is '''monochrome''' with white forecolor and black background. +* '''SCREEN 7''' can use 16 ([[DAC]]) colors with background colors. RGB settings can be changed in colors 0 to 7 using [[_PALETTECOLOR]]. * '''SCREEN 8''' has 16 color attributes with 16 background colors. - -* '''SCREEN 9''' can use up to 64 [[DAC]] color hues in 16 color attributes with background colors assigned to attribute 0 with a {{KW|PALETTE}} swap. RGB settings can be changed in colors 0 to 5 and 7 using {{KW|OUT}}. - +* '''SCREEN 9''' can use up to 64 [[DAC]] color hues in 16 color attributes with background colors assigned to attribute 0 with a [[_PALETTECOLOR]] swap. RGB settings can be changed in colors 0 to 5 and 7 using [[_PALETTECOLOR]]. * '''SCREEN 10''' has '''only 4 color attributes''' with black background. COLOR 0 = black, 1 = grey, 2 = flash white and 3 = bright white. - -* '''SCREEN 11''' is '''monochrome''' with white forecolor and a black background, '''Cannot use the COLOR statement!''' - -* '''SCREEN 12''' can use 16 color attributes with a black background. 256K possible RGB color hues. - +* '''SCREEN 11''' is '''monochrome''' with white forecolor and a black background. +* '''SCREEN 12''' can use 16 color attributes with a black background. 256K possible RGB color hues. Background colors can be used with QB64. * '''SCREEN 13''' can use 256 color attributes with a black background. 256K possible RGB hues. - -* [[DAC]] screens 0, 7 and 9 color changes are limited in '''Qbasic ONLY'''! - -* [[PALETTE]] swaps can be made in SCREEN 7 and 9 only. Those screens were [[DAC]] screen modes in Qbasic. +* [[PALETTE]] swaps can be made in SCREEN 7 and 9 only. Those screens were [[DAC]] screen modes in QBasic. * [[_DEST]] can be used to set the destination page or image to color using '''QB64'''. * [[_DEFAULTCOLOR]] returns the current color being used on an image or screen page handle. -<center>'''24/32 Bit Colors using QB64'''</center> - -* Pixel color intensities for Red, Green, Blue and Alpha range from 0 to 255 when used with [[_RGB]], [[_RGBA]], [[_RGB32]] and [[RGBA32]]. -* Combined RGB function values returned are [[LONG]] values! '''Blue intensity values may be cut off using [[SINGLE]] values!''' +===24/32-Bit colors using QB64=== +* Pixel color intensities for red, green, blue and alpha range from 0 to 255 when used with [[_RGB]], [[_RGBA]], [[_RGB32]] and [[RGBA32]]. +* Combined RGB function values returned are [[LONG]] values. '''Blue intensity values may be cut off using [[SINGLE]] variables.''' * [[_ALPHA]] transparency values can range from 0 as transparent up to 255 which is fully opaque. * [[_CLEARCOLOR]] can also be used to set a color as transparent. -* Colors can be mixed by using [[_BLEND]](default) in 32 bit screen modes ONLY. [[_DONTBLEND]] disables blending. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* Colors can be mixed by using [[_BLEND]] (default) in 32-bit screen modes. [[_DONTBLEND]] disables blending. +* '''NOTE: Default 32-bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> ==RGB Palette Intensities== -RGB intensity values can be converted to Hexadecimal values to create the [[LONG]] [[_PALETTECOLOR]] value in non-32 bit screens: +RGB intensity values can be converted to hexadecimal values to create the [[LONG]] [[_PALETTECOLOR]] value in non-32-bit screens: {{CodeStart}} '' '' {{Cl|SCREEN}} 12 alpha$ = "FF" 'solid alpha colors only @@ -101,46 +80,28 @@ alpha$ = "FF" 'solid alpha colors only {{text|COLOR 14 <nowiki>=</nowiki> &HFFFCFC54 FC FC 54|#FCFC54}} {{text|COLOR 15 <nowiki>=</nowiki> &HFFFCFCFC FC FC FC|#FCFCFC}} {{OutputEnd}} -:''Explanation:'' The RGB intensity values are multiplied by 4 to get the [[_RGB]] intensity values as [[HEX$|Hexadecimal]] values. The individual 2 digit [[HEX$]] intensity values can be added to "&HFF" to make up the 32 bit hexadecimal string value necessary for [[VAL]] to return to [[_PALETTECOLOR]]. The statement is only included in the example to show how that can be done with any 32 bit color value. -<center>'''Note:''' Black has a blue hex value of 50 due to the [[OUT]] background color setting which makes it dark blue.</center> +:''Explanation:'' The RGB intensity values are multiplied by 4 to get the [[_RGB]] intensity values as [[HEX$|hexadecimal]] values. The individual 2 digit [[HEX$]] intensity values can be added to "&HFF" to make up the 32-bit hexadecimal string value necessary for [[VAL]] to return to [[_PALETTECOLOR]]. The statement is only included in the example to show how that can be done with any 32-bit color value. +:'''Note:''' Black has a blue hex value of 50 due to the [[OUT]] background color setting which makes it dark blue. -<center>'''Reading and setting Color Port intensities using [[INP]] and [[OUT]]'''</center> +===Reading and setting color port intensities using [[INP]] and [[OUT]]=== +* Legacy code may use [[INP]] and [[OUT]] to read or set color port intensities. '''QB64''' emulates VGA memory to maintain compatibility. +* The same can be achieved using [[_PALETTECOLOR]] ('''recommended practice'''). -::::::::'''{{text|OUT &H3C7, attribute|green}}''' 'Set port to read RGB settings with: -:::::::::'''{{text|color_intensity <nowiki>=</nowiki> INP(&H3C9)|green}}''' 'reads present intensity setting +:'''{{text|OUT &H3C7, attribute|green}}''' 'Set port to read RGB settings with: +:'''{{text|color_intensity <nowiki>=</nowiki> INP(&H3C9)|green}}''' 'reads present intensity setting -::::::::'''{{text|OUT &H3C8, attribute|green}}''' 'Set port to write RGB settings with: -:::::::::'''{{text|OUT &H3C9, color_intensity|green}}''' 'writes new intensity setting +:'''{{text|OUT &H3C8, attribute|green}}''' 'Set port to write RGB settings with: +:'''{{text|OUT &H3C9, color_intensity|green}}''' 'writes new intensity setting * After every 3 reads or writes, changes to next higher color attribute. Loops can be used to set more than one attribute's intensities. -* Color port setting of Red, Green and Blue intensities can be done in ascending order. -* Color port attribute intensity values range from 0 to 63(1/4 of the 32 bit values) only in Qbasic 4 and 8 bit screen modes. - - -<center>'''Hexadecimal 32 bit colors can be set in 16 or 256 color screen modes with [[_PALETTECOLOR]]'''</center> - -''Example:'' Changing light gray text in [[SCREEN]] 0 to a 32 bit custom color using a [[LONG]] HTML hexadecimal value: -{{CodeStart}} '' '' -{{Cl|COLOR}} 7 -{{Cl|PRINT}} "Color 7 is gray" -K$ = {{Cl|INPUT$}}(1) -{{Cl|_PALETTECOLOR}} 7, {{Cl|&H}}FFDAA520 ' FF alpha makes the color translucent -{{Cl|PRINT}} "Color 7 is now Goldenrod in {{Cl|SCREEN}} 0! '' '' -{{CodeEnd}} -{{OutputStart}} -{{text|Color 7 is gray|#A8A8A8}} -{{text|Color 7 is now Goldenrod in SCREEN 0!|#DAA520}} -{{OutputEnd}} -: ''Explanation:'' [[_RGB32]] could be used to make custom 32 bit colors or HTML values could be used after &HFF for solid colors. - - -''See also:'' [[HEX$ 32 Bit Values]] to learn more about hexadecimal color values. +* Color port setting of red, green and blue intensities can be done in ascending order. +* Color port attribute intensity values range from 0 to 63 (1/4 of the 32-bit values) in QBasic's legacy 4 and 8 bit screen modes. <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> -==Examples:== +{{PageExamples}} ''Example 1:'' Reading the default RGB color settings of color attribute 15. {{CodeStart}} '' '' {{Cl|OUT}} &H3C7, 15 @@ -227,28 +188,34 @@ text$ = "HelloWorld" : ''Explanation:''Semicolon(;) means that the next PRINT happens on the same line, we don't want that when it comes to position 5 so when it is at position 5 the next PRINT will move to the next line (when it isn't at position 5 we want it to continue printing the letter side-by-side on the same line though). -''Example 7:'' Since SCREEN 0 only uses background colors 0 to 7 by default, use [[OUT]] to change color intensities of color 0 in QB64 only. +''Example 7:'' Since SCREEN 0 only uses background colors 0 to 7 by default, use [[_PALETTECOLOR]] to change color intensities of color 0. {{CodeStart}} '' '' -{{Cl|OUT}} {{Cl|&H}}3C8, 0 'change color 0 intensities -{{Cl|OUT}} {{Cl|&H}}3C9, 63 -{{Cl|OUT}} {{Cl|&H}}3C9, 63 -{{Cl|OUT}} {{Cl|&H}}3C9, 63 - -{{Cl|OUT}} {{Cl|&H}}3C8, 8 'change color 8 intensities -{{Cl|OUT}} {{Cl|&H}}3C9, 0 -{{Cl|OUT}} {{Cl|&H}}3C9, 0 -{{Cl|OUT}} {{Cl|&H}}3C9, 0 +{{Cl|_PALETTECOLOR}} 0, _RGB32(255, 255, 255) 'change color 0 intensity +{{Cl|_PALETTECOLOR}} 8, _RGB32(0, 0, 0) 'change color 8 intensity {{Cl|COLOR}} 8: {{Cl|PRINT}} "Black on bright white!" '' '' {{CodeEnd}} {{WhiteStart}}'''{{text|Black on bright white!|#000000}}''' {{WhiteEnd}} ---- -: ''Explanation:'' Since QB64 does not use [[DAC]] [[SCREEN]] 0 limitations, changing color intensities for custom background colors is possible. +: ''Explanation:'' Since QB64 does not have [[DAC]] [[SCREEN]] 0 limitations, changing color intensities for custom background colors is possible. + +''Example 8:'' Changing light gray text in [[SCREEN]] 0 to a 32 bit custom color using a [[LONG]] HTML hexadecimal value: +{{CodeStart}} '' '' +{{Cl|COLOR}} 7 +{{Cl|PRINT}} "Color 7 is gray" +K$ = {{Cl|INPUT$}}(1) +{{Cl|_PALETTECOLOR}} 7, {{Cl|&H}}FFDAA520 ' FF alpha makes the color translucent +{{Cl|PRINT}} "Color 7 is now Goldenrod in {{Cl|SCREEN}} 0! '' '' +{{CodeEnd}} +{{OutputStart}} +{{text|Color 7 is gray|#A8A8A8}} +{{text|Color 7 is now Goldenrod in SCREEN 0!|#DAA520}} +{{OutputEnd}} +: ''Explanation:'' [[_RGB32]] could be used to make custom 32 bit colors or HTML values could be used after &HFF for solid colors. <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> -==References:== {{PageSeeAlso}} * [[_RGB]], [[_RGBA]], [[_RGB32]], [[RGBA32]]. @@ -258,6 +225,7 @@ text$ = "HelloWorld" * [[PRINT]], [[LOCATE]], [[SCREEN]] * [[POINT]], [[SCREEN (function)]] * [[OUT]], [[INP]], [[PALETTE]] +* [[_BLINK]] * [[_DEFAULTCOLOR]] * [[_BACKGROUNDCOLOR]] * [[_PALETTECOLOR]] diff --git a/internal/help/COMMAND$.txt b/internal/help/COMMAND$.txt index e895deddb..dab07ba2a 100644 --- a/internal/help/COMMAND$.txt +++ b/internal/help/COMMAND$.txt @@ -1,20 +1,18 @@ -The '''COMMAND$''' [[STRING]] function returns the spaced [[DOS]] command line argument(s) passed when a program is run. - +The '''COMMAND$''' function returns the command line argument(s) passed when a program is run. {{PageSyntax}} -::: option$ = [[COMMAND$]][(count%)] +: {{Parameter|commandLine$}} = [[COMMAND$]][(count%)] -* Useful when the programmer wants to send specific program options to the command line for later use by the called program. -* The [[STRING]] return value is any '''spaced quoted or unquoted''' parameter(s) following the filename in a [[RUN]] or command line statement. -* '''QB64''' does not '''require or return all [[UCASE$|uppercase]]''' values so keep that fact in mind when checking parameters passed! -* In '''QB64 only''', COMMAND$ can work as an array to return specific elements passed to the command line. COMMAND$(2) would return the '''spaced''' second parameter passed at the command line. This can be used on modern operating systems to successfully retrieve file names and arguments which contain spaces properly. (versions after May 20, 2015) -* Use the [[_COMMANDCOUNT]] function to find the number of spaced parameters passed to a program via the command line. (versions after May 20, 2015) '''{{text|See ''Example 2''|green}}'''. -* Reading the spaced command options in the '''COMMAND$(i)''' array in a loop can also be done and reading a COMMAND$ without parameters is also possible. (versions after May 20, 2015) '''{{text|See ''Example 3''|green}}'''. -* COMMAND$ was '''not available in QuickBasic versions below 4.0''' and returned [[UCASE$|uppercase]] [[STRING]] parameters no matter what case they were sent originally. +{{PageDescription}} +* The [[STRING]] return value is anything typed after a program's executable file name in command line (or using the [[RUN]] statement). +* Unlike QuickBASIC, '''QB64''' does not return all [[UCASE$|uppercase]] values so keep that in mind when checking parameters. +* In '''QB64''', COMMAND$ works as an array to return specific elements passed to the command line. COMMAND$(2) would return the second parameter passed at the command line. Arguments can contain spaces if they are passed inside quotation marks. This can be used to properly retrieve file names and arguments which contain spaces. +* Use the [[_COMMANDCOUNT]] function to find the number of parameters passed to a program via the command line. See ''Example 2'' below. +{{PageExamples}} ''Example 1:'' Compile both programs. ProgramA [[RUN]]s ProgramB with a parameter passed following the filename: {{CodeStart}} {{Cl|LOCATE}} 12, 36: {{Cl|PRINT}} "ProgramA" @@ -28,7 +26,7 @@ K$ = {{Cl|INPUT$}}(1) : ''ProgramB'' checks for fullscreen parameter pass in QB64 and goes full screen. {{CodeStart}} '' '' {{Cl|LOCATE}} 17, 36: {{Cl|PRINT}} "ProgramB" -parameter$ = {{Cl|UCASE$}}({{Cl|COMMAND$}}) 'QB64 only as QB4.5 will always return upper case +parameter$ = {{Cl|UCASE$}}({{Cl|COMMAND$}}) 'UCASE$ is needed in QB64 only, as QB4.5 will always return upper case {{Cl|LOCATE}} 20, 33: {{Cl|PRINT}} "Parameter = " + parameter$ {{Cl|IF...THEN|IF}} {{Cl|LEFT$}}(parameter$, 2) = "FS" {{Cl|THEN}} {{Cl|_FULLSCREEN}} 'parameter changes to full screen @@ -55,7 +53,7 @@ a data file : ''Explanation: If we start ''ThisProgram.exe'' with the command line '''ThisProgram -l "a data file"''', COMMAND$ will return a single string of "-1 a data file" which might be hard to process and interpret properly, but COMMAND$(1) would return "-l" and COMMAND$(2) would return the quoted "a data file" option as separate entries for easier parsing and processing. -''Example 3:'' As part of the command array upgrade, you can also just read the array to see how many commands were sent: +''Example 3:'' As part of the command array syntax, you can also just read the array to see how many commands were sent (or simply check [[_COMMANDCOUNT]]): {{CodeStart}}DO count = count + 1 cmd$ = {{Cl|COMMAND$}}(count) @@ -64,10 +62,9 @@ a data file {{Cl|LOOP}} '' '' count = count - 1 'save the number of parameters sent to this program when run {{CodeEnd}} -:'''Note:''' When using this command [[DO]] loop read procedure, the spaced commands sent must not be empty strings as the count will end! -''See also:'' +{{PageSeeAlso}} * [[SHELL]], [[RUN]] * [[UCASE$]], [[LCASE$]] * [[_COMMANDCOUNT]] diff --git a/internal/help/COMMON.txt b/internal/help/COMMON.txt index ff11d22a9..f47d13f54 100644 --- a/internal/help/COMMON.txt +++ b/internal/help/COMMON.txt @@ -1,31 +1,25 @@ -'''COMMON''' shares common variable values with other Linked or [[CHAIN]]ed modules. +[[COMMON]] shares common variable values with other linked or [[CHAIN]]ed modules. + +==Legacy support== +* The multi-modular technique goes back to when QBasic and QuickBASIC had module size constraints. In QB64 [[COMMON]] has been implemented so that that older code can still be compiled, though '''it is advisable to use single modules for a single project (not counting [[$INCLUDE]] libraries), for ease of sharing and also because the module size constraints no longer exist.''' -::::::''Syntax:'' COMMON [SHARED] [/blockname/] variablelist +{{PageSyntax}} +: [[COMMON]] [SHARED] variableList +{{PageDescription}} * COMMON must be called before any executable statements. - * [[SHARED]] makes the variables shared within [[SUB]] and [[FUNCTION]] procedures within that module. - -* /blockname/ gives the ability to name a block of variables (ex. COMMON /thename/ a, b, c), this name can later be referenced in the module to only give access to those variables. As such, many COMMON statements can be issued with different names to be shared in different modules. - -* Variablelist is the list of common variables made available separated by commas. - +* variableList is the list of common variables made available separated by commas. * Remember to keep the variable type ''order'' the same in all modules, as the variables names don't matter. - * [[COMMON SHARED]] is most commonly used to share the variables with subs and functions of that module. - -* In Qbasic, Common variables can only be passed by [[CHAIN]] using compiled modules if BRUN45.EXE is included with the program. - -* Linked files are compiled first and linked with LINK.EXE in QB. '''QB64''' cannot link files presently! -* '''Note: Values assigned to shared variables used as procedure call parameters will not be passed to other procedures! The shared variable value MUST be assigned INSIDE of the [[SUB]] or [[FUNCTION]] procedure to be passed!''' +* '''Note: Values assigned to shared variables used as procedure call parameters will not be passed to other procedures. The shared variable value must be assigned inside of the [[SUB]] or [[FUNCTION]] procedure to be passed.''' -''See also:'' +{{PageSeeAlso}} * [[COMMON SHARED]], [[CHAIN]] * [[DIM]], [[REDIM]], [[SHARED]] * [[DEFSTR]], [[DEFLNG]], [[DEFINT]], [[DEFSNG]], [[DEFDBL]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CONST.txt b/internal/help/CONST.txt index 9d43a7890..3692ea83e 100644 --- a/internal/help/CONST.txt +++ b/internal/help/CONST.txt @@ -1,27 +1,29 @@ -The {{KW|CONST}} statement globally defines one or more named numeric or string values which will not change while a program is running. +The [[CONST]] statement globally defines one or more named numeric or string values which will not change while the program is running. {{PageSyntax}} -: '''CONST {{Parameter|constantName}} = {{Parameter|value}}'''[, ...] +: [[CONST]] {{Parameter|constantName}} = {{Parameter|value}}[, ...] {{Parameters}} * {{Parameter|constantName}} is the constant name or list of names assigned by the programmer. -* {{Parameter|value}} is the value to initialize the global constant which cannot change once defined: +* {{Parameter|value}} is the value to initialize the global constant which cannot change once defined. ** If {{Parameter|constantName}} specifies a numeric type, {{Parameter|value}} must be a numeric expression containing literals and other constants. ** If {{Parameter|constantName}} specifies a string type, the {{Parameter|value}} must be a literal value. -''Usage:'' -* The {{Parameter|constantName}} does not have to include a type suffix! The datatype can be determined by the {{Parameter|value}}. -* Constant values cannot use a variable, [[SUB]] or [[FUNCTION]] return value when defined. -* Constants cannot be re-assigned values. They retain the same value throughout all of the program procedures. +{{PageDescription}} +* The {{Parameter|constantName}} does not have to include a type suffix. The datatype is automatically infered by the compiler using the {{Parameter|value}}. +* Constant values cannot reference a variable, [[SUB]] or [[FUNCTION]] return values when defined. +** The exception to the above are color functions [[_RGB32]] and [[_RGBA32]], which can be used in a CONST statement. See ''Example 2'' below. +* Constants cannot be reassigned values. They retain the same value throughout all of the program procedures. * Constants defined in module-level code have [[SHARED|shared]] scope, so they can also be used in [[SUB]] or [[FUNCTION]] procedures. -* Constants defined in {{KW|SUB}} or {{KW|FUNCTION}} procedures are local to those procedures. +* Constants defined in [[SUB]] or [[FUNCTION]] procedures are local to those procedures. * [[CLEAR]] will not affect or change constant values. -''Example:'' Display the circumference and area of circles: +{{PageExamples}} +''Example 1:'' Display the circumference and area of circles: {{CodeStart}}' Declare a numeric constant approximately equal to the ratio of a circle's ' circumference to its diameter: {{Cl|CONST}} PI = 3.141593 @@ -48,12 +50,21 @@ The area of the circle is 47882.23 Enter the radius of a circle or zero to quit? ''0'' {{OutputEnd}} -: ''Explanation:'' PI cannot change as it is a mathematical constant so it is fitting to define it as a constant. Trying to change PI will result in a programming error. +: ''Explanation:'' PI cannot change as it is a mathematical constant so it is fitting to define it as a constant. Trying to change PI will result in a calculation error. +''Example 2'': Using _RGB32 to set a constant's value. +{{CodeStart}} '' '' +{{Cl|CONST}} Red = _RGB32(255,0,0) + +{{Cl|COLOR}} Red +{{Cl|PRINT}} "Hello World" +{{CodeEnd}} + {{PageSeeAlso}} -* {{KW|DIM}}, {{KW|SHARED}} -* {{KW|STATIC}}, {{KW|COMMON}} +* [[DIM]], [[SHARED]] +* [[STATIC]], [[COMMON]] +* [[_PI]], [[_RGB32]], [[_RGBA32]] * [http://doc.pcsoft.fr/en-US/?6510001 Windows 32 API constant values] diff --git a/internal/help/COS.txt b/internal/help/COS.txt index 06ba54ebb..05212f301 100644 --- a/internal/help/COS.txt +++ b/internal/help/COS.txt @@ -1,23 +1,23 @@ -The '''COS''' function returns the horizontal component or the cosine of an angle measured in radians. - +The [[COS]] function returns the horizontal component or the cosine of an angle measured in radians. {{PageSyntax}} -::: value! = '''COS('''''radian_angle!''''')''' +: {{Parameter|value!}} = [[COS]]({{Parameter|radianAngle!}}) {{Parameters}} -* The ''radian_angle'' must be measured in radians. +* The {{Parameter|radianAngle!}} must be measured in radians. {{PageDescription}} -* To convert from degrees to radians, multiply degrees * π/180. +* To convert from degrees to radians, multiply degrees * &pi; / 180. * [[COS]]INE is the horizontal component of a unit vector in the direction theta (&theta;). * COS(x) can be calculated in either [[SINGLE]] or [[DOUBLE]] precision depending on its argument. ::: COS(4) = -.6536436 ...... COS(4#) = -.6536436208636119 -''Example 1:'' Converting degree angles to radians for Qbasic's trig functions and drawing the line at the angle. +{{PageExamples}} +''Example 1:'' Converting degree angles to radians for QBasic's trig functions and drawing the line at the angle. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 PI = 4 * {{Cl|ATN}}(1) @@ -94,7 +94,7 @@ DEGREES% = RADIANS * 180 / PI = 45 {{small|Code by Ben}} -''See also:'' +{{PageSeeAlso}} * [[_PI]] {{text|(QB64 function)}} * [[SIN]] {{text|(sine)}} * [[ATN]] {{text|(arctangent)}} diff --git a/internal/help/CSNG.txt b/internal/help/CSNG.txt index 4dc3d8c53..94004eb2f 100644 --- a/internal/help/CSNG.txt +++ b/internal/help/CSNG.txt @@ -1,21 +1,20 @@ -'''CSNG''' -To converts a numerical value to the closest [[SINGLE]]-precision number. +[[CSNG]] converts a numerical value to the closest [[SINGLE]]-precision number. {{PageSyntax}} -:: singlevalue = '''CSNG('''''expression''''')''' +: {{Parameter|singleValue!}} = [[CSNG]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[TYPE]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} -* Returns the closest [[SINGLE]] decimal point value +* Returns the closest [[SINGLE]] decimal point value. * Also used to define a value as [[SINGLE]]-precision up to 7 decimals. -''Example:'' +{{PageExamples}} {{CodeStart}} A# = 975.3421222# PRINT A#, CSNG(A#) diff --git a/internal/help/CSRLIN.txt b/internal/help/CSRLIN.txt index 5f35dcefe..5809f5774 100644 --- a/internal/help/CSRLIN.txt +++ b/internal/help/CSRLIN.txt @@ -1,16 +1,20 @@ -The '''CSRLIN''' function returns the current text row position of the [[PRINT]] cursor. +The [[CSRLIN]] function returns the current text row position of the [[PRINT]] cursor. -::::::::{{PageSyntax}} row% = CSRLIN +{{PageSyntax}} +: {{Parameter|row%}} = [[CSRLIN]] {{PageDescription}} * The value returned is within the range of 1 to the current number of rows in the [[SCREEN]] mode used. +** In [[SCREEN]] 0 (text mode), the [[_HEIGHT]] function returns the number of text rows. +** In graphic modes, the number of available text rows can be calculated by dividing [[_HEIGHT]] (measured in pixels in graphic modes) by [[_FONTHEIGHT]]: '''''totalRows%'' = _HEIGHT / _FONTHEIGHT''' * In screen modes that support page flipping, the [[CSRLIN]] function returns the vertical coordinate of the cursor on the active page. * x = [[POS]](0) returns the column location of the cursor. +{{PageExamples}} ''Example:'' A semicolon stops the print cursor immediately after the print. {{CodeStart}} '' '' LOCATE 5, 5: PRINT "HELLO "; @@ -35,10 +39,10 @@ The '''CSRLIN''' function returns the current text row position of the [[PRINT]] {{OutputEnd}} -:''Explanation:'' "HELLO " is printed and the semicolon stops the cursor immediately after the text. The '''CSRLIN''' variable records the current print cursor's text row in Y. The [[POS]] function records the current print cursor's text column in X. The second [[PRINT]] statement displays the comment "WORLD" on the 10th line of the screen. The last [[LOCATE]] statement restores the position of the cursor to the original line and column immediately after the first print. +:''Explanation:'' "HELLO " is printed and the semicolon stops the cursor immediately after the text. The [[CSRLIN]] variable records the current print cursor's text row in Y. The [[POS]] function records the current print cursor's text column in X. The second [[PRINT]] statement displays the comment "WORLD" on the 10th line of the screen. The last [[LOCATE]] statement restores the position of the cursor to the original line and column immediately after the first print. -''See also:'' +{{PageSeeAlso}} * [[SCREEN]], [[LOCATE]], [[POS]] * [[_PRINTSTRING]] (graphic print) diff --git a/internal/help/CVD.txt b/internal/help/CVD.txt index 0d505e3f7..992b544c5 100644 --- a/internal/help/CVD.txt +++ b/internal/help/CVD.txt @@ -1,20 +1,19 @@ -The '''CVD''' function converts 8 byte [[GET]] or [[MKD$]] [[STRING]] values to [[DOUBLE]] numeric values. +The [[CVD]] function decodes an 8-byte [[STRING]] generated by [[MKD$]] (or read from a file) to [[DOUBLE]] numeric values. -::::::''Syntax:'' CVD(''8-byte string'') +{{PageSyntax}} +: {{Parameter|result#}} = [[CVD]]({{Parameter|stringData$}}) -* The 8 byte string value was created by [[MKD$]] or [[PUT]]. -* Numeric values read from a [[RANDOM]]-access or [[BINARY]] file must be converted from [[ASCII]] string characters back into numbers if they are to be arithmetically manipulated. +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* Variables of numerical types are also encoded when [[PUT]] to a [[RANDOM]] or [[BINARY]]-access file. +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. * [[DOUBLE]] values can range up to 15 decimal point digits. Decimal point accuracy depends on whole value places taken. -* [[CVD]] converts an 8-byte string created by [[MKD$]] to a [[DOUBLE]]-precision numerical value. -* [[CVS]] converts a 4-byte string created by [[MKS$]] to a [[SINGLE]]-precision numerical value. -* [[CVI]] converts a 2-byte string created by [[MKI$]] to an [[INTEGER]] numerical value. -* [[CVL]] converts a 4 byte string created by [[MKL$]] to a [[LONG]] integer numerical value. -* CV functions can only be used to convert values from [[MK$]] string function values or data from [[BINARY]] files! -''Examples:'' +{{PageExamples}} +''Example 1:'' Reading an 8-byte encoded string n$ from a file and obtaining the decoded [[DOUBLE]] value: {{CodeStart}} '' '' {{Cl|FIELD}} #1, 8 {{Cl|AS}} N$, 12 {{Cl|AS}} B$... {{Cl|GET}} #1 @@ -22,13 +21,29 @@ Y# = {{Cl|CVD}}(N$) '' '' {{CodeEnd}} : ''Explanation:'' Reads a field from file #1, and converts the first eight bytes (N$) into an double-precision number assigned to the variable Y#. -:Since a double-precision number can contain as many as 15 ASCII characters (fifteen bytes), writing a file using [[MKD$]] conversion, and reading with the [[CVD]] conversion, as many as 7 bytes per number recorded are saved on the storage medium. + +''Example 2:'' Showcases the reduced space to store an encoded number. +{{CodeStart}} +a# = 77000.24523213 +{{Cl|PRINT}} "Value of a#:"; a# +b$ = {{Cl|MKD$}}(a#) +{{Cl|PRINT}} "Value of a# encoded using MKD$: "; b$ +{{Cl|PRINT}} "The string above, decoded using CVD:"; {{Cl|CVD}}(b$) +{{CodeEnd}} +{{OutputStart}} +Value of a#: 77000.24523213 + +Value of a# encoded using MKD$: ñåxýâ╠‗@ + +The string above, decoded using CVD: 77000.24523213 +{{OutputEnd}} +:Since the representation of a double-precision number can use up to 15 ASCII characters (fifteen bytes), writing to a file using [[MKD$]] conversion, and then reading back with the [[CVD]] conversion can save up to 7 bytes of storage space. -''See also:'' - -* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]] -* [[CVI]], [[CVS]], [[CVL]] +{{PageSeeAlso}} +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVI]], [[CVS]], [[CVL]], [[CVSMBF]], [[CVDMBF]] * [[_CV]], [[_MK$]] diff --git a/internal/help/CVDMBF.txt b/internal/help/CVDMBF.txt index 95fc58aa1..19e712572 100644 --- a/internal/help/CVDMBF.txt +++ b/internal/help/CVDMBF.txt @@ -1,18 +1,39 @@ -The '''CVDMBF''' function converts a 8-byte string containing a Microsoft Binary format number to a double precision IEEE-format number. +The [[CVDMBF]] function decodes an 8-byte [[STRING]] generated by [[MKDMBF$]] (or read from a file) to [[DOUBLE]] numeric values. -::::''Syntax: value = CVDMBF(string_value) +{{PageSyntax}} +: {{Parameter|result#}} = [[CVDMBF]]({{Parameter|stringData$}}) -* CVDMBF reads [[RANDOM]]-access or [[BINARY]] files containing [[MKDMBF$]] [[STRING|string]] values stored in the Microsoft Binary format. +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. +* [[DOUBLE]] values can range up to 15 decimal point digits. Decimal point accuracy depends on whole value places taken. +{{PageExamples}} +''Example 1:'' Showcases the reduced space to store an encoded number. +{{CodeStart}} +a# = 77000.24523213 +{{Cl|PRINT}} "Value of a#:"; a# +b$ = {{Cl|MKDMBF$}}(a#) +{{Cl|PRINT}} "Value of a# encoded using MKDMBF$: "; b$ +{{Cl|PRINT}} "The string above, decoded using CVDMBF:"; {{Cl|CVDMBF}}(b$) +{{CodeEnd}} +{{OutputStart}} +Value of a#: 77000.24523213 -''See also:'' +Value of a# encoded using MKDmbf$: 5─c▼d▬æ -* [[CVSMBF]] +The string above, decoded using CVDMBF: 77000.24523213 +{{OutputEnd}} +:Since the representation of a double-precision number can use up to 15 ASCII characters (fifteen bytes), writing to a file using [[MKDMBF$]] conversion, and then reading back with the [[CVDMBF]] conversion can save up to 7 bytes of storage space. -* [[MKDMBF$]], [[MKSMBF$]] + +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVI]], [[CVS]], [[CVD]], [[CVL]], [[CVSMBF]] +* [[_CV]], [[_MK$]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CVI.txt b/internal/help/CVI.txt index 439348452..e9cac43b8 100644 --- a/internal/help/CVI.txt +++ b/internal/help/CVI.txt @@ -1,18 +1,18 @@ -The '''CVI''' function converts 2 byte [[GET]] or [[MKI$]] [[STRING]] values to [[INTEGER]] numeric values. +The [[CVI]] function decodes a 2-byte [[STRING]] generated by [[MKI$]] (or read from a file) to [[INTEGER]] numeric values. -::::::''Syntax:'' CVI(''2-byte string'') +{{PageSyntax}} +: {{Parameter|result%}} = [[CVI]]({{Parameter|stringData$}}) -* Numeric values read from a [[RANDOM]]-access or [[BINARY]] disk file must be converted from [[ASCII]] string characters back into numbers if they are to be arithmetically manipulated. +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. * [[INTEGER]] values can range from -32768 to 32767. -* [[CVI]] converts a 2-byte string created by [[MKI$]] to an [[INTEGER]] numerical value. -* [[CVL]] converts a 4 byte string created by [[MKL$]] to a [[LONG]] integer numerical value. -* [[CVS]] converts a 4-byte string created by [[MKS$]] to a [[SINGLE]]-precision numerical value. -* [[CVD]] converts an 8-byte string created by [[MKD$]] to a [[DOUBLE]]-precision numerical value. -* CV functions can only be used to convert values from [[MK$]] string function values or data from [[BINARY]] files! +* Doesn't return [[_UNSIGNED]] values. +{{PageExamples}} ''Example 1:'' {{CodeStart}} '' '' {{Cl|FIELD}} #1, 2 {{Cl|AS}} N$, 12 {{Cl|AS}} B$... @@ -20,13 +20,12 @@ The '''CVI''' function converts 2 byte [[GET]] or [[MKI$]] [[STRING]] values to Y = {{Cl|CVI}}(N$) '' '' {{CodeEnd}} :''Explanation:'' Reads a field from file #1, and converts the first two bytes (N$) into an integer number assigned to the variable Y. - -:Since an integer number can contain as many as five ASCII characters (five bytes), writing a file using [[MKI$]] conversion, and reading with the CVI conversion, as many as three bytes per number recorded are saved on the storage medium. +:Since the representation of an integer number can use up to 5 ASCII characters (five bytes), writing to a file using [[MKI$]] conversion, and then reading back with the [[CVI]] conversion can save up to 3 bytes of storage space. ''Example 2:'' How CVI converts the ASCII code values created by the MKI$ function. {{CodeStart}} -{{Cl|SCREEN (statement)|SCREEN}} 12 '_PRINTSTRING requires a graphic screen mode +{{Cl|SCREEN (statement)|SCREEN}} 12 {{Cl|DIM}} Q {{Cl|AS}} {{Cl|STRING}} * 1 Q = {{Cl|CHR$}}(34) ' create Print using templates to align the values returned @@ -54,15 +53,13 @@ tmp4$ = " CVI Total = ##### " {{Cl|SYSTEM}} '' '' {{CodeEnd}} {{small|Code by Ted Weissgerber}} -:''Explanation:'' All [[ASCII]] characters can be displayed using [[_PRINTSTRING]] . The routine gets the [[ASCII]] code, which is the actual value needed by [[CVI]]. The first byte code is always between 0 and 255. The second byte can return 0 thru 127 and CVI multiplies that value by 256. This proves that you cannot just feed a string number value to [[CVI]] and get the result desired! "90" = 12345. +:''Explanation:'' All [[ASCII]] characters can be displayed using [[_PRINTSTRING]] . The routine gets the [[ASCII]] code, which is the actual value needed by [[CVI]]. The first byte code is always between 0 and 255. The second byte can return 0 thru 127 and CVI multiplies that value by 256. This proves that you cannot just feed a string number value to [[CVI]] and get the result desired. ("90" gets decoded to 12345). -''See also:'' -* [[MKI$]], [[ASC]] -* [[MKL$]], [[CVL]] -* [[MKS$]], [[CVS]] -* [[MKD$]], [[CVD]] -* [[Bitmaps]] +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVS]], [[CVD]], [[CVL]], [[CVSMBF]], [[CVDMBF]] +* [[_CV]], [[_MK$]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CVL.txt b/internal/help/CVL.txt index de771cc71..790b3f58b 100644 --- a/internal/help/CVL.txt +++ b/internal/help/CVL.txt @@ -1,18 +1,18 @@ -The '''CVL''' function converts 4 byte [[GET]] or [[MKL$]] [[STRING]] values to [[LONG]] numeric values. +The [[CVL]] function decodes a 4-byte [[STRING]] generated by [[MKL$]] (or read from a file) to [[LONG]] numeric values. -::::::''Syntax:'' CVL(''4-byte string'') +{{PageSyntax}} +: {{Parameter|result&}} = [[CVL]]({{Parameter|stringData$}}) -* Numeric values read from a [[RANDOM]]-access or [[BINARY]] disk file must be converted from [[ASCII]] string characters back into numbers if they are to be arithmetically manipulated. -* [[LONG]] Integer values can be from -2147483648 to 2147483647. -* [[CVL]] converts a 4 byte string created by [[MKL$]] to a [[LONG]] integer numerical value. -* [[CVI]] converts a 2-byte string created by [[MKI$]] to an [[INTEGER]] numerical value. -* [[CVS]] converts a 4-byte string created by [[MKS$]] to a [[SINGLE]]-precision numerical value. -* [[CVD]] converts an 8-byte string created by [[MKD$]] to a [[DOUBLE]]-precision numerical value. -* CV functions can only be used to convert values from [[MK$]] string function values or data from [[BINARY]] files! +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. +* [[LONG]] values can range from -2147483648 to 2147483647. +* Doesn't return [[_UNSIGNED]] values. +{{PageExamples}} ''Example 1: 4 byte [[ASCII]] character strings show how CVL multipliers convert [[MKL$]] values into a 4 byte [[LONG]] value. {{CodeStart}} '' '' {{Cl|PRINT}} {{Cl|CVL}}({{Cl|CHR$}}(1) + {{Cl|STRING$}}(3, 0)) '{{Cl|ASC}}(CHR$(1)) * 1 = 1 @@ -30,15 +30,13 @@ Y& = {{Cl|CVL}}(N$) '' '' {{CodeEnd}} :''Explanation:'' Reads a field from file #1, and converts the first four bytes (N$) into a long integer value assigned to the variable Y&. -:Since a long number can contain as many as ten ASCII characters (ten bytes), writing a file using [[MKL$]] conversion, and reading with the CVL conversion, as many as six bytes per number recorded are saved on the storage medium. +:Since the representation of a long number can use up to 10 ASCII characters (ten bytes), writing to a file using [[MKL$]] conversion, and then reading back with the [[CVL]] conversion can save up to 6 bytes of storage space. -''See also:'' -* [[MKL$]], [[MKI$]], [[MKS$]], [[MKD$]] -* [[CVI]], [[CVS]], [[CVD]] +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVI]], [[CVS]], [[CVD]], [[CVDMBF]], [[CVSMBF]] * [[_CV]], [[_MK$]] -* [[Bitmaps]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CVS.txt b/internal/help/CVS.txt index 5ab4a7e5d..6c493a8c6 100644 --- a/internal/help/CVS.txt +++ b/internal/help/CVS.txt @@ -1,35 +1,37 @@ -The '''CVS''' function converts 2 byte [[GET]] or [[MKS$]] [[STRING]] values to [[SINGLE]] floating decimal numerical values. +The [[CVS]] function decodes a 4-byte [[STRING]] generated by [[MKS$]] (or read from a file) to [[SINGLE]] numeric values. - -::::::''Syntax:'' CVS(''2-byte string'') +{{PageSyntax}} +: {{Parameter|result!}} = [[CVS]]({{Parameter|stringData$}}) - -* Numeric values read in from a [[RANDOM]]-access or [[BINARY]] disk file must be converted from [[ASCII]] string characters back into numbers if they are to be arithmetically manipulated. +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. * [[SINGLE]] values can range up to 7 decimal point digits. Decimal point accuracy depends on whole value places taken. -* [[CVS]] converts a 4-byte string created by [[MKS$]] to a [[SINGLE]]-precision numerical value. -* [[CVD]] converts an 8-byte string created by [[MKD$]] to a [[DOUBLE]]-precision numerical value. -* [[CVI]] converts a 2-byte string created by [[MKI$]] to an [[INTEGER]] numerical value. -* [[CVL]] converts a 4 byte string created by [[MKL$]] to a [[LONG]] integer numerical value. -* CV functions can only be used to convert values from [[MK$]] string function values or data from [[BINARY]] files! -''Examples:'' -{{CodeStart}} '' '' -{{Cl|FIELD}} #1, 4 {{Cl|AS}} N$, 12 {{Cl|AS}} B$... -{{Cl|GET}} #1 -Y = {{Cl|CVS}}(N$) '' '' +{{PageExamples}} +''Example 1:'' Showcases the reduced space to store an encoded number. +{{CodeStart}} +a! = 700.2213 +{{Cl|PRINT}} "Value of a!:"; a! +b$ = {{Cl|MKDMBF$}}(a!) +{{Cl|PRINT}} "Value of a# encoded using MKS$: "; b$ +{{Cl|PRINT}} "The string above, decoded using CVS:"; {{Cl|CVS}}(b$) {{CodeEnd}} -:''Explanation:'' Reads a field from file #1, and converts the first four bytes (N$) into a single-precision number assigned to the variable Y. - -:Since a single-precision number can contain as many as seven ASCII characters (seven bytes), writing a file using [[MKS$]] conversion, and reading with the [[CVS]] conversion, as many as three bytes per number recorded are saved on the storage medium. Even more may be saved if double-precision numbers are required. [[MKD$]] and [[CVD]] conversions would be used in this case. +{{OutputStart}} +Value of a!: 700.2213 +Value of a# encoded using MKS: *♫/D +The string above, decoded using CVS: 700.2213 +{{OutputEnd}} +:Since the representation of a single-precision number can use up to 7 ASCII characters (seven bytes), writing to a file using [[MKS$]] conversion, and then reading back with the [[CVS]] conversion can save up to 3 bytes of storage space. -''See also:'' -* [[MKS$]], [[MKI$]], [[MKL$]], [[MKD$]] -* [[CVI]], [[CVL]], [[CVD]], [[_CV]] -* [[_MK$]], [[_CV]] +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVI]], [[CVD]], [[CVL]], [[CVDMBF]], [[CVSMBF]] +* [[_CV]], [[_MK$]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/CVSMBF.txt b/internal/help/CVSMBF.txt index c2ed23d29..5ac039c51 100644 --- a/internal/help/CVSMBF.txt +++ b/internal/help/CVSMBF.txt @@ -1,18 +1,37 @@ -The '''CVSMBF''' function converts a 4-byte string containing a Microsoft Binary format value to a single precision IEEE-format number. +The [[CVDMBF]] function decodes a 4-byte [[STRING]] generated by [[MKSMBF$]] (or read from a file) to [[SINGLE]] numeric values. -''Syntax:'' value! = CVSMBF(string_value) +{{PageSyntax}} +: {{Parameter|result!}} = [[CVSMBF]]({{Parameter|stringData$}}) -* CVSMBF read [[RANDOM]]-access or [[BINARY]] files containing numbers stored as [[STRING|strings]] in the Microsoft Binary format. +{{PageDescription}} +* ''CV'' functions ([[CVD]], [[CVS]], [[CVI]], [[CVL]], [[CVDMBF]], [[CVSMBF]]) are used to convert values encoded by ''MK$'' functions ([[MKD$]], [[MKS$]], [[MKI$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]]). +* '''QB64''' has [[_CV]] and [[_MK$]] functions which can also deal with extended [[Data types|data types]]. +* [[SINGLE]] values can range up to 7 decimal point digits. Decimal point accuracy depends on whole value places taken. +{{PageExamples}} +''Example 1:'' Showcases the reduced space to store an encoded number. +{{CodeStart}} +a! = 700.2213 +{{Cl|PRINT}} "Value of a!:"; a! +b$ = {{Cl|MKSMBF$}}(a!) +{{Cl|PRINT}} "Value of a! encoded using MKSMBF$: "; b$ +{{Cl|PRINT}} "The string above, decoded using CVSMBF:"; {{Cl|CVDMBF}}(b$) +{{CodeEnd}} +{{OutputStart}} +Value of a!: 700.2213 +Value of a# encoded using MKSMBF$: *♫/è +The string above, decoded using CVSMBF: 700.2213 +{{OutputEnd}} +:Since the representation of a double-precision number can use up to 7 ASCII characters (seven bytes), writing to a file using [[MKSMBF$]] conversion, and then reading back with the [[CVSMBF]] conversion can save up to 3 bytes of storage space. -''See also:'' -* [[CVDMBF]] - -* [[MKDMBF$]], [[MKSMBF$]] +{{PageSeeAlso}} +* [[MKD$]], [[MKI$]], [[MKS$]], [[MKL$]], [[MKDMBF$]], [[MKSMBF$]] +* [[CVI]], [[CVS]], [[CVD]], [[CVL]], [[CVDMBF]] +* [[_CV]], [[_MK$]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/DATA.txt b/internal/help/DATA.txt index 20b738cb0..d189b8875 100644 --- a/internal/help/DATA.txt +++ b/internal/help/DATA.txt @@ -1,24 +1,27 @@ -The '''DATA''' statement creates a line of fixed program information separated by commas. The DATA can be READ by the program. +The [[DATA]] statement creates a line of fixed program information separated by commas. The DATA can be later READ by the program at runtime. -''Syntax:'' DATA [value1, value2, ...] +{{PageSyntax}} +: [[DATA]] [value1, value2, ...] +{{PageDescription}} * DATA is used at the beginning of every data field line with commas separating the values that follow. -* Values can be any '''literal''' [[STRING]] or numerical type. '''Variables cannot be used!''' +* Values can be any '''literal''' [[STRING]] or numerical type. '''Variables cannot be used.''' * DATA fields can be placed and READ consecutively in the main program code body with or without line labels for [[RESTORE]]. -* DATA is best placed after the main program code. '''QB64 DATA can be placed inside a [[SUB]] or [[FUNCTION]] procedures!''' -* [[RESTORE]] will only read the first data field if the DATA is not labeled or RESTORE call uses no label. -* When using multiple DATA fields, label each data field with a line label so that '''each''' data pointer can be reset for multiple reads with [[RESTORE]] ''linelabel''. Otherwise RESTORE will only read the '''first''' data field! -* QB comma separations were flexible to allow column alignments when creating them. QB64 removes spacing between commas. -* [[STRING]] DATA values with end spaces, QB keywords and commas in them '''require''' quotation marks. +* DATA is best placed after the main program code. +** '''QB64''' DATA can be placed inside a [[SUB]] or [[FUNCTION]] procedures. +* [[RESTORE]] will only read the first data field if the DATA is not labeled or no label is specified in a RESTORE call. +* When using multiple DATA fields, label each data field with a line label so that each data pointer can be reset for multiple reads with '''[[RESTORE]] ''linelabel'''''. +* QBasic comma separations were flexible to allow column alignments when creating them. QB64 removes spacing between commas. +* [[STRING]] DATA values with end spaces, QBasic keywords and values that include the comma character must be enclosed in quotation marks. * DATA fields can only be created by the programmer and cannot be changed by a user or lost. * Comments after a data line require a colon before the comment. -* If a [[READ]] is past the last data value, an [[ERROR Codes|"Out of Data" error]] will occur! Use end of data markers when necessary! -: Qbasic allowed programmers to add DATA fields anywhere because the [[IDE]] separated the main code from other procedures. -* '''Do not place labeled [[DATA]] fields after [[SUB]] or [[FUNCTION]] procedures! QB64 will FAIL to [[RESTORE]] properly!''' +* If a [[READ]] statement attempts to read past the last data value, an [[ERROR Codes|"Out of Data" error]] will occur. Use end of data markers when necessary. +* '''[[DATA]] fields can be placed after [[SUB]] or [[FUNCTION]] procedures, but line labels are not allowed.''' +{{PageExamples}} ''Example 1:'' Creating two DATA fields that can be [[READ]] repeatedly using [[RESTORE]] with the appropriate line label. {{CodeStart}} '' '' {{Cl|RESTORE}} Database2 @@ -45,7 +48,7 @@ Database2: {{OutputEnd}} -''Example 2:'' How to [[RESTORE]] and [[READ]] DATA in a [[SUB]] procedure in QB64 only. Line labels can be used for multiple DATA fields. +''Example 2:'' How to [[RESTORE]] and [[READ]] DATA in a [[SUB]] procedure in QB64. Line labels can be used for multiple DATA fields. {{CodeStart}} '' '' {{Cl|DIM}} {{Cl|SHARED}} num(10) 'shared array or must be passed as a parameter ReadData 2 '<<<<<<< change value to 1 to read other data @@ -67,10 +70,9 @@ mydata2: {{Cl|END SUB}} '' '' {{CodeEnd}} {{OutputStart}} 10 9 8 7 6 5 4 3 2 1 {{OutputEnd}} -: ''Note:'' A specific array index can be passed in a parameter or the entire array can be passed using empty brackets. -''See also:'' +{{PageSeeAlso}} * [[READ]] * [[RESTORE]] * [[SUB]], [[FUNCTION]] diff --git a/internal/help/DATE$.txt b/internal/help/DATE$.txt index c572c7e9c..6aa0a7c99 100644 --- a/internal/help/DATE$.txt +++ b/internal/help/DATE$.txt @@ -1,14 +1,15 @@ -The '''DATE$''' Function returns the present computer date as a string in a month, day and 4 digit year format. +The [[DATE$]] function returns the current computer date as a string in the format "mm-dd-yyyy". -:::::''Syntax:'' today$ = DATE$ +{{PageSyntax}} +: {{Parameter|today$}} = [[DATE$]] -* Returns the present computer date in a mm-dd-yyyy format such as: "12-25-2009" -* Returns "-" (dash) separators between month, day and year on most machines. -* '''NOTE''': Older computers may just use the last two digit years! +{{PageDescription}} +* Returns the current computer date in the format "mm-dd-yyyy" (e.g., "12-25-2009"). +{{PageExamples}} ''Example:'' Displaying the weekday and current date. {{CodeStart}} '' '' {{Cl|PRINT}} {{Cl|DATE$}} @@ -31,8 +32,9 @@ year$ = {{Cl|RIGHT$}}({{Cl|DATE$}}, 4): Y = {{Cl|VAL}}(year$) {{Cl|CASE}} 12: Moon$ = "December" {{Cl|END SELECT}} {{Cl|PRINT}} "Today is " + WeekDay$(M, D, Y) + ", " + Moon$ + day$ + ", " + year$ + {{Cl|SPACE$}}(10) - -{{Cl|FUNCTION}} WeekDay$ (M, D, Y) + +{{Cl|DEFINT}} A-Z +{{Cl|FUNCTION}} WeekDay$ (M, D, Y) {{Cl|IF}} M < 3 {{Cl|THEN}} M = M + 12: Y = Y - 1 'add 12 to Jan - Feb month, -1 year C = Y \ 100: Y = Y {{Cl|MOD}} 100 'split century and year number S1 = (C \ 4) - (2 * C) - 1 'century leap @@ -57,13 +59,10 @@ WeekDay$ = day$ 06-02-2010 Today is Wednesday, June 2, 2010 {{OutputEnd}} -:'''NOTE:''' When using {{KW|DEFINT}} A-Z in the main program, place DEFINT A-Z before FUNCTION WeekDay$ line. -''See also:'' - +{{PageSeeAlso}} * [[DATE$ (statement)]], [[TIME$]], [[TIME$ (statement)]] - * [[VAL]], [[STR$]], [[MID$]], [[LEFT$]], [[IF...THEN]] diff --git a/internal/help/DATE$_(statement).txt b/internal/help/DATE$_(statement).txt index b6e3bce81..620b87373 100644 --- a/internal/help/DATE$_(statement).txt +++ b/internal/help/DATE$_(statement).txt @@ -1,23 +1,26 @@ -The '''DATE$''' statement sets the current computer date to another [[STRING]] value. +'''This page is maintained for historic purposes. The keyword is not supported in QB64. Reading the current date is supported with the [[DATE$|DATE$ function]].''' + +---- + +The [[DATE$]] statement sets the current computer date to another [[STRING]] value. -:::''Syntax:'' DATE$ = String_expression +{{PageSyntax}} +: [[DATE$]] = {{Parameter|stringExpression$}} - - -* String expression can use slash or dash formats when assigning the date: +* {{Parameter|stringExpression$}} can use slash or dash as separators: ::::mm-dd-yyyy ::::mm/dd/yyyy -* String expression or variable must contain the months, day and 4 digit year to be changed (10 valid characters). +* String expression or variable must contain the month, day and 4 digit year to be changed (10 valid characters). * If value is not a valid formatted string, a "Type Mismatch" error results. The previous DATE$ value will be retained. * The current date (as assigned when the operating system was initialized) can be saved to restore later with the [[DATE$]] function. *The DATE$ function returns a 10-character string in the form ''mm-dd-yyyy''. ''mm'' is the month (01 to 12), ''dd'' is the day (01 to 31), and ''yyyy'' is the four digit year. * '''Note: Some systems may not allow the DATE to be reset or require Administrator privileges.''' Try a batch file or [[SHELL]]. -* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] +{{PageExamples}} ''Example:'' Backdating computer to run old software. {{CodeStart}} @@ -39,10 +42,8 @@ The '''DATE$''' statement sets the current computer date to another [[STRING]] v -''See also:'' - +{{PageSeeAlso}} [[DATE$]], [[TIME$]], [[TIME$ (statement)]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/DECLARE.txt b/internal/help/DECLARE.txt index 91058c58b..e70c70900 100644 --- a/internal/help/DECLARE.txt +++ b/internal/help/DECLARE.txt @@ -1,3 +1,8 @@ +'''This page is maintained for historic purposes. The usage of the DECLARE keyword explained below isn't required/implemented in QB64. QB64 ignores any occurrences of DECLARE SUB/FUNCTION when older code is compiled. For the modern usage of the DECLARE keyword (for external C procedures), see [[DECLARE LIBRARY]].''' + +---- + + The '''DECLARE''' statement is used to tell Qbasic that a [[SUB]] or [[FUNCTION]] is to be used in the program with specific parameter types. diff --git a/internal/help/DECLARE_(non-BASIC_statement).txt b/internal/help/DECLARE_(non-BASIC_statement).txt index b3592dd42..fb697add5 100644 --- a/internal/help/DECLARE_(non-BASIC_statement).txt +++ b/internal/help/DECLARE_(non-BASIC_statement).txt @@ -1,3 +1,8 @@ +'''This page is maintained for historic purposes. The usage of the DECLARE keyword explained below isn't supported by QB64. QB64 ignores any occurrences of DECLARE SUB/FUNCTION when older code is compiled. For the modern usage of the DECLARE keyword, see [[DECLARE LIBRARY]].''' + +---- + + Declares calling sequences for external procedures written in other languages. @@ -6,7 +11,6 @@ Declares calling sequences for external procedures written in other languages. : [[DECLARE]] {[[SUB]]|[[FUNCTION]]} name [ [[CDECL]] ] [ [[ALIAS]] "aliasname"] [([parameterlist, ...])] -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' * [[CDECL]] indicates that the procedure uses the C language argument order. * [[ALIAS]] indicates the procedure name used in the object or library file. * The syntax for the parameterlist is as follows: [{ [[BYVAL]] | [[SEG]] }] variable [AS type [,[{ [[BYVAL]] | [[SEG]] }] variable2 [ [[AS]] type]]... @@ -17,7 +21,7 @@ Declares calling sequences for external procedures written in other languages. ''See also:'' * [[CALL]], [[CALLS]], [[SETMEM]] -* [[DECLARE LIBRARY]] (QB64 Only} +* [[DECLARE LIBRARY]] (QB64 Only) diff --git a/internal/help/DECLARE_DYNAMIC_LIBRARY.txt b/internal/help/DECLARE_DYNAMIC_LIBRARY.txt index a7c84e0fa..8f524cd11 100644 --- a/internal/help/DECLARE_DYNAMIC_LIBRARY.txt +++ b/internal/help/DECLARE_DYNAMIC_LIBRARY.txt @@ -2,29 +2,37 @@ {{PageSyntax}} -::: DECLARE [DYNAMIC|CUSTOMTYPE|STATIC] LIBRARY [''"DLL_Library_file"'', "other_library..."] -::: {SUB|FUNCTION} [''procedure_name'' ALIAS] ''library_procedure'' (BYVAL ''parameter(s)'',...) -::::. -::::. 'other Library sub-procedures for named ''DLL'' -::::. -::: END DECLARE +: DECLARE [DYNAMIC|CUSTOMTYPE|STATIC] LIBRARY [''"DLL_Library_file"'', "other_library..."] +: {SUB|FUNCTION} [''procedure_name'' ALIAS] ''library_procedure'' (BYVAL ''parameter(s)'',...) +::. +::. 'other Library sub-procedures for named ''DLL'' +::. +: END DECLARE -* '''This QB64 procedure is available as of WINDOWS version .923 and Linux and Mac version 0.94 releases!''' +{{PageDescription}} * The dynamic library file can be located in the QB64 folder (alongside your programs '.EXE'), in Windows' system32 folder, or in a relative/absolute path specified along with the library name. -* '''Declarations MUST be made at the program start and only one ''.DLL'' file can be specified in each declaration block.''' -* ''Library_file'' is the ''DLL'' file's name with a specified path when not in the QB64 or the WINDOWS\SYSTEM32 folder. No extension! +* '''Declarations must be made at the program start and only one ''.DLL'' file can be specified in each declaration block.''' +* ''Library_file'' is the ''DLL'' file's name with a specified path when not in the QB64 or the WINDOWS\SYSTEM32 folder. Don't add a file extension. * ''Library filename''s can be listed to combine more than one DLL or Header file name or path into one DECLARE LIBRARY block. * ''Procedure_name'' is any procedure name you want to designate by using [[ALIAS]] with the ''Library_procedure'' name following. * ''Parameters'' used by the Library procedure must be passed by value ([[BYVAL]]) except for [[STRING]] values. -* '''''.h'' header files cannot be used with DECLARE DYNAMIC LIBRARY. Existence of any ''.h'' file of the same name as the ''.DLL'' file will cause DECLARE DYNAMIC LIBRARY to fail!''' -* '''IMPORTANT:''' [[DECLARE DYNAMIC LIBRARY]] let's you specify any SUB/FUNCTION calling format you wish, but '''if the size of the parameters does not match, the size expected within the library your code will probably cause a GPF(General Protection Fault)!''' It is important to understand that you are creating a 32-bit program (even under 64-bit Windows) so '''pointers (if required) will be 32-bits in size, the equivalent of a [[LONG]].''' +* '''''.h'' header files cannot be used with DECLARE DYNAMIC LIBRARY. Existence of any ''.h'' file of the same name as the ''.DLL'' file will cause DECLARE DYNAMIC LIBRARY to fail.''' +* '''IMPORTANT:''' [[DECLARE DYNAMIC LIBRARY]] let's you specify any SUB/FUNCTION calling format you wish, but '''if the size of the parameters does not match, the size expected within the library your code will probably cause a GPF (General Protection Fault).''' It is important to understand that you are creating a 32-bit program (even under 64-bit Windows) so '''pointers (if required) will be 32-bits in size, the equivalent of a [[LONG]].''' * '''STATIC''' is the same as [[DECLARE LIBRARY]] except that it prioritizes linking to static libraries (*.a/*.o) over shared object (*.so) libraries, if both exist. As Windows doesn't really use shared libraries (DLLs are a bit different) this does not affect Windows users. * The [[_OFFSET]] in memory can be used in '''CUSTOMTYPE''', '''STATIC''' and '''DYNAMIC LIBRARY''' declarations. +* [[SUB]] procedures using DECLARE CUSTOMTYPE LIBRARY API procedures '''may error'''. Try DYNAMIC with the DLL name. * Declarations can be made inside of [[SUB]] or [[FUNCTION]] procedures. Declarations do not need to be at program start. -* '''NOTE: It is up to the user to document and determine the suitability of all Libraries and procedures they choose to use! QB64 cannot guarantee that ANY procedure will work and cannot quarantee ANY troubleshooting help!''' +* '''NOTE: It is up to the user to document and determine the suitability of all Libraries and procedures they choose to use. QB64 cannot guarantee that any procedure will work and cannot quarantee any troubleshooting help.''' +==Availability== +* '''Version 0.923 and up (Windows)''' +* '''Version 0.94 and up (Linux and macOS)''' + + + +{{PageExamples}} ''Example 1:'' This example plays Midi files using the ''playmidi32.dll'' documented here: [http://libertybasicuniversity.com/lbnews/nl110/midi3.htm Liberty Basic University].                         Download the following DLL file to your main QB64 folder: [http://www.qb64.net/playmidi32.dll PlayMidi32.dll] {{CodeStart}} '' '' {{Cl|DECLARE DYNAMIC LIBRARY}} "playmidi32" @@ -77,8 +85,11 @@ QuickUTF16toUTF32$ = b$ {{Cl|END FUNCTION}} '' '' {{CodeEnd}} {{small|Code by Galleon}} +: '''Note:''' SUB procedures using CUSTOMTYPE LIBRARY API procedures inside may error. Try DYNAMIC with "KERNEL32". -<center>'''Note: QB64 requires all DLL files to either be with the program or in the C:\WINDOWS\SYSTEM32 folder!'''</center> + +<center>'''QB64 version 1.000 and up produce standalone executables. External DLL files must be distributed with your program.'''</center> +<center>'''Note: QB64 versions prior to 1.000 require all default DLL files to either be with the program or in the C:\WINDOWS\SYSTEM32 folder.'''</center> ''See also:'' diff --git a/internal/help/DECLARE_LIBRARY.txt b/internal/help/DECLARE_LIBRARY.txt index 5b77408d8..3026cc6d4 100644 --- a/internal/help/DECLARE_LIBRARY.txt +++ b/internal/help/DECLARE_LIBRARY.txt @@ -2,28 +2,30 @@ The '''DECLARE LIBRARY''' declaration allows the use of external library [[SUB]] {{PageSyntax}} -::: '''DECLARE''' [DYNAMIC|CUSTOMTYPE|STATIC] '''LIBRARY''' [{''"Library_filename"''|''"Headerfile"''}] -::: {[[SUB]]|[[FUNCTION]]} [''procedure_name'' {{KW|ALIAS}}] ''library_procedure'' ([{{KW|BYVAL}}] ''parameter {{KW|AS}}'', ...) -::::. -::::. 'other SUBs or Functions as required -::::. -::: '''END DECLARE''' +: '''DECLARE''' [DYNAMIC|CUSTOMTYPE|STATIC] '''LIBRARY''' [{''"Library_filename"''|''"Headerfile"''}] +: {[[SUB]]|[[FUNCTION]]} [''procedure_name'' {{KW|ALIAS}}] ''library_procedure'' ([{{KW|BYVAL}}] ''parameter {{KW|AS}}'', ...) +::. +::. 'other SUBs or Functions as required +::. +: '''END DECLARE''' {{Parameters}} -* The ''Library name'' is needed if a Library is NOT already loaded by QB64. Do not include the ''.DLL'', ''LIB'' or ''.H'' file extension. -* ''Procedure_name'' is any program procedure name you want to designate by using [[ALIAS]] with the ''Library_procedure'' name. -* ''Library procedure'' is the actual procedure name used inside of the library or header file. +* The {{Parameter|Library_filename}} is needed if a Library is not already loaded by QB64. Do not include the ''.DLL'', ''LIB'' or ''.H'' file extension. +** It's always a good idea to try declaring Windows API libraries without a {{Parameter|Library_filename}} first, as most Windows headers are already included in QB64 source. +* Begin the {{Parameter|Library_filename}} with '''./''' or '''.\''' to make it relative to the path where your source file is saved, so you can keep all your project files together. +* {{Parameter|Procedure_name}} is any program procedure name you want to designate by using [[ALIAS]] with the {{Parameter|Library_procedure}} name. +* {{Parameter|Library procedure}} is the actual procedure name used inside of the library or header file. -''Library Types:'' +===Library Types=== * '''[[DECLARE DYNAMIC LIBRARY|DYNAMIC]]''' links a program to functions in dynamically linkable libraries. At present, only .DLL files are supported -* '''CUSTOMTYPE''' is already implied when using [[DECLARE DYNAMIC LIBRARY]]. This type of library just allows the same flexibility to apply when referencing STATIC libraries that are used to refer to dynamic libraries. Supports shared object (*.so) libraries +* '''CUSTOMTYPE''' is already implied when using [[DECLARE DYNAMIC LIBRARY]]. This type of library just allows the same flexibility to apply when referencing STATIC libraries that are used to refer to dynamic libraries. Supports shared object (*.so) libraries. * '''STATIC''' is the same as [[DECLARE LIBRARY]] except that it prioritizes linking to static libraries (*.a/*.o) over shared object (*.so) libraries, if both exist. As Windows doesn't use shared libraries (DLLs are different) this does not affect Windows users. {{PageDescription}} -* The declaration can be used with C++ sub-procedures, Windows API and QB64 SDL Libraries. +* The declaration can be used with C++ sub-procedures, Windows API and QB64 SDL (versions prior to 1.000)/OpenGL (version 1.000 and up) Libraries. * ''Library filename''s can be listed to combine more than one DLL or Header file name or path into one DECLARE LIBRARY block. * C procedures can use a header file name. File code must be included with program code. Do not include the ''.h'' extension. * ''Parameters'' used by the Library procedure must be passed by value ([[BYVAL]]) except for [[STRING]] characters. @@ -31,10 +33,11 @@ The '''DECLARE LIBRARY''' declaration allows the use of external library [[SUB]] * The [[_OFFSET]] in memory can be used in '''CUSTOMTYPE''', '''STATIC''' and '''DYNAMIC LIBRARY''' declarations. * Declarations can be made inside of [[SUB]] or [[FUNCTION]] procedures. Declarations do not need to be at program start. -* '''NOTE: It is up to the user to document and determine the suitability of all Libraries and procedures they choose to use! QB64 cannot guarantee that ANY procedure will work and cannot quarantee ANY troubleshooting help!''' +* '''NOTE: It is up to the user to document and determine the suitability of all Libraries and procedures they choose to use! QB64 cannot guarantee that any procedure will work and cannot quarantee any troubleshooting help.''' -''Example 1:'' Using a '''QB64 SDL ONLY''' library procedure as a program SUB procedure to move the mouse pointer to a coordinate. +{{PageExamples}} +''Example 1:'' Using an '''SDL''' library procedure as a program SUB procedure to move the mouse pointer to a coordinate (works in versions prior to 1.000): {{CodeStart}} '' '' {{Cl|DECLARE LIBRARY}} {{Cl|SUB}} SDL_WarpMouse ({{Cl|BYVAL}} column {{Cl|AS}} {{Cl|LONG}}, {{Cl|BYVAL}} row {{Cl|AS}} {{Cl|LONG}}) 'SDL procedure name @@ -55,7 +58,7 @@ SDL_WarpMouse x, y 'call SDL library procedure {{Cl|END SUB}} '' '' {{CodeEnd}} {{small|Code by Galleon}} -:''Explanation:'' The SDL Library is already included and loaded with QB64, so these procedures are directly available for use. +:''Explanation:'' The SDL Library is included and loaded with QB64 versions prior to 1.000, so these procedures are directly available for use. <center>'''Using [[ALIAS]] to create a program SUB or FUNCTION''' using '''QB64 SDL ONLY'''</center> {{CodeStart}} '' '' @@ -111,29 +114,20 @@ PRINT "&H" + HEX$(GetLPTPortAddress%(1)) {{TextEnd}} -<center>'''SDL Library Documentation'''</center> -:Library documentation is downloadable here in PS format: Use either [http://get.adobe.com/reader/ Acrobat Reader] or [http://download.cnet.com/PDF-XChange-Viewer/3000-10743_4-10598377.html PDF XChange Viewer] - -<center>[http://www.libsdl.org/archives/sdldoc-ps.zip SDL Library Ebook Documentation Download]</center> - -: Note: Unzip the downloaded "SDLdoc.PS" file and click on it. Make it into an Ebook in top choice box where it says Screen. - -<center>[http://www.libsdl.org/archives/sdldoc-html.zip SDL Library HTML Browser References]</center> - - <center>Galleon's '''OpenGL''' Library with demo program download: http://www.qb64.net/gl_package.zip</center> -<center>'''Note: QB64 requires all DLL files to either be with the program or in the C:\WINDOWS\SYSTEM32 folder!'''</center> +<center>'''QB64 version 1.000 and up produce standalone executables. External DLL files must be distributed with your program.'''</center> +<center>'''Note: QB64 versions prior to 1.000 require all default DLL files to either be with the program or in the C:\WINDOWS\SYSTEM32 folder.'''</center> ''See also:'' * [[DECLARE DYNAMIC LIBRARY]] * [[SUB]], [[FUNCTION]] * [[BYVAL]], [[ALIAS]] -* [[C Libraries]], [[SDL Libraries]], [[DLL Libraries]], [[Windows Libraries]] +* [[C Libraries]], [[DLL Libraries]], [[Windows Libraries]] * [[Port Access Libraries]] -* [[OpenGL Libraries]] +* [[OpenGL Libraries]], [[SDL Libraries]] * [[SFML Libraries]] * [[SQL Client]] * [http://www.qb64.net/forum/index.php?topic=11810.msg102081#msg102081 DECLARE LIBRARY and C++ Variable Types] diff --git a/internal/help/DEFDBL.txt b/internal/help/DEFDBL.txt index b8290863c..118e870a8 100644 --- a/internal/help/DEFDBL.txt +++ b/internal/help/DEFDBL.txt @@ -1,22 +1,38 @@ -The '''DEFDBL''' statement defines all designated undefined variables AS [[DOUBLE]] variables instead of the [[SINGLE]] type default. +The [[DEFDBL]] statement defines all variables with names starting with the specified letter (or letter range) AS [[DOUBLE]] variables instead of the [[SINGLE]] type default. + + +==Legacy support== +* '''DEF''' statements ([[DEFDBL]], [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]]) were used when storage space was a concern in older computers, as their usage could save up typing. Instead of {{InlineCode}}'''DIM a AS DOUBLE, a2 AS DOUBLE, a3 AS DOUBLE'''{{InlineCodeEnd}}, simply having {{InlineCode}}'''DEFDBL A'''{{InlineCodeEnd}} in the code before using variables starting with letter '''A''' would do the same job. +* '''For clarity, it is recommended to declare variables with meaningful names'''. {{PageSyntax}} -:: '''DEFDBL ''letter'''''[-''range''] +: [[DEFDBL]] {{Parameter|letter}}[-{{Parameter|range}}], {{Parameter|letter2}}[-{{Parameter|range2}}], [...] -* The first letters can be from A-Z or any other range. +{{PageDescription}} +* {{Parameter|letter}} (or {{Parameter|range}}) can be from A-Z or any other range, like '''G-M'''. * You can also use commas for specific undefined variable first letters. -* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not defined otherwise. -* DEFDBL sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''Qbasic's IDE may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures!''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not affected by [[DEFDBL]]. +* [[DEFDBL]] sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''Example:'' DEFDBL A, F, H +==QBasic/QuickBASIC== +* QBasic's IDE would add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64 (like QBasic) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures. -''See also:'' +{{PageExamples}} +{{CodeStart}} +{{Cl|DEFDBL}} A, F-H, M + +'With the above, all variables with names starting with A, F, G, H and M +'will be of type DOUBLE, unless they have a type suffix +'indicating another type or they are {{Cl|DIM|dimensioned}} differently +{{CodeEnd}} + + +{{PageSeeAlso}} * [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]] * [[_DEFINE]] diff --git a/internal/help/DEFINT.txt b/internal/help/DEFINT.txt index 8d80d740f..4540d1e21 100644 --- a/internal/help/DEFINT.txt +++ b/internal/help/DEFINT.txt @@ -1,29 +1,41 @@ -The '''DEFINT''' statement defines all designated undefined variables AS [[INTEGER]] variables instead of the [[SINGLE]] type default. +The [[DEFINT]] statement defines all variables with names starting with the specified letter (or letter range) AS [[INTEGER]] variables instead of the [[SINGLE]] type default. + + +==Legacy support== +* '''DEF''' statements ([[DEFDBL]], [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]]) were used when storage space was a concern in older computers, as their usage could save up typing. Instead of {{InlineCode}}'''DIM a AS INTEGER, a2 AS INTEGER, a3 AS INTEGER'''{{InlineCodeEnd}}, simply having {{InlineCode}}'''DEFINT A'''{{InlineCodeEnd}} in the code before using variables starting with letter '''A''' would do the same job. +* '''For clarity, it is recommended to declare variables with meaningful names'''. {{PageSyntax}} -:: '''DEFSINT ''letter'''''[-''range''] +: [[DEFINT]] {{Parameter|letter}}[-{{Parameter|range}}], {{Parameter|letter2}}[-{{Parameter|range2}}], [...] -* The variable first letters can be from A-Z or any other range. -* You can also use commas for specific untyped variable first letters. -* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not defined otherwise. -* DEFINT allows users to create larger graphical arrays up to the integer limits. -* The maximum value of a signed Integer variable is 32767. Minimum is -32768. -* [[UNSIGNED]] Integer values from 0 to 65535 must use [[_DEFINE]] -* DEFINT sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''Qbasic's IDE may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures!''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +{{PageDescription}} +* {{Parameter|letter}} (or {{Parameter|range}}) can be from A-Z or any other range, like '''G-M'''. +* You can also use commas for specific undefined variable first letters. +* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not affected by [[DEFINT]]. +* [[DEFINT]] sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* For [[_UNSIGNED]] [[INTEGER]], use [[_DEFINE]] +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''Examples:'' -:: DEFINT A-Z -:: DEFINT A-D, Z -:: DEFINT A, I, O +==QBasic/QuickBASIC== +* QBasic's IDE would add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64 (like QBasic) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures. -''See also:'' -* [[DEFSNG]], [[DEFLNG]], [[DEFDBL]], [[DEFSTR]], [[_DEFINE]] +{{PageExamples}} +{{CodeStart}} +{{Cl|DEFINT}} A, F-H, M + +'With the above, all variables with names starting with A, F, G, H and M +'will be of type INTEGER, unless they have a type suffix +'indicating another type or they are {{Cl|DIM|dimensioned}} differently +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[DEFSNG]], [[DEFLNG]], [[DEFDBL]], [[DEFSTR]] +* [[_DEFINE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/DEFLNG.txt b/internal/help/DEFLNG.txt index 049055144..b5b2f814e 100644 --- a/internal/help/DEFLNG.txt +++ b/internal/help/DEFLNG.txt @@ -1,24 +1,40 @@ -The '''DEFLNG''' statement defines all designated undefined variables AS [[LONG]] variables instead of the [[SINGLE]] type default. +The [[DEFLNG]] statement defines all variables with names starting with the specified letter (or letter range) AS [[LONG]] variables instead of the [[SINGLE]] type default. + + +==Legacy support== +* '''DEF''' statements ([[DEFDBL]], [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]]) were used when storage space was a concern in older computers, as their usage could save up typing. Instead of {{InlineCode}}'''DIM a AS LONG, a2 AS LONG, a3 AS LONG'''{{InlineCodeEnd}}, simply having {{InlineCode}}'''DEFLNG A'''{{InlineCodeEnd}} in the code before using variables starting with letter '''A''' would do the same job. +* '''For clarity, it is recommended to declare variables with meaningful names'''. {{PageSyntax}} -:: '''DEFSTR ''letter'''''[-''range''] +: [[DEFLNG]] {{Parameter|letter}}[-{{Parameter|range}}], {{Parameter|letter2}}[-{{Parameter|range2}}], [...] -* The variable first letters can be from A-Z or any other range. +{{PageDescription}} +* {{Parameter|letter}} (or {{Parameter|range}}) can be from A-Z or any other range, like '''G-M'''. * You can also use commas for specific undefined variable first letters. -* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not defined otherwise. -* [[UNSIGNED]] [[LONG]] Integer values from 0 to 4,294,967,295 must use [[_DEFINE]]. -* DEFLNG sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''Qbasic's IDE may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures!''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not affected by [[DEFLNG]]. +* [[DEFLNG]] sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* For [[_UNSIGNED]] [[LONG]], use [[_DEFINE]] +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''Example:'' DEFLNG F-H, T +==QBasic/QuickBASIC== +* QBasic's IDE would add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64 (like QBasic) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures. -''See also:'' -* [[DEFINT]], [[DEFSNG]], [[DEFDBL]], [[DEFSTR]] +{{PageExamples}} +{{CodeStart}} +{{Cl|DEFLNG}} A, F-H, M + +'With the above, all variables with names starting with A, F, G, H and M +'will be of type LONG, unless they have a type suffix +'indicating another type or they are {{Cl|DIM|dimensioned}} differently +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[DEFSNG]], [[DEFDBL]], [[DEFINT]], [[DEFSTR]] * [[_DEFINE]] diff --git a/internal/help/DEFSNG.txt b/internal/help/DEFSNG.txt index cbab4cfd7..555f55be0 100644 --- a/internal/help/DEFSNG.txt +++ b/internal/help/DEFSNG.txt @@ -1,24 +1,40 @@ -The '''DEFSNG''' statement defines all designated undefined variables AS [[SINGLE]] variables. +The [[DEFSNG]] statement defines all variables with names starting with the specified letter (or letter range) AS [[SINGLE]] variables. + + +==Legacy support== +* '''DEF''' statements ([[DEFDBL]], [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]]) were used when storage space was a concern in older computers, as their usage could save up typing. Instead of {{InlineCode}}'''DIM a AS SINGLE, a2 AS SINGLE, a3 AS SINGLE'''{{InlineCodeEnd}}, simply having {{InlineCode}}'''DEFSNG A'''{{InlineCodeEnd}} in the code before using variables starting with letter '''A''' would do the same job. +* '''For clarity, it is recommended to declare variables with meaningful names'''. {{PageSyntax}} -:: '''DEFSNG ''letter'''''[-''range''] +: [[DEFSNG]] {{Parameter|letter}}[-{{Parameter|range}}], {{Parameter|letter2}}[-{{Parameter|range2}}], [...] -* The variable first letters can be from A-Z or any other range. -* You can also use commas for specific untyped variable first letters. -* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not defined otherwise. -* DEFSNG is normally the Qbasic default type assignment for undefined variables without type suffixes. -* DEFSNG sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''Qbasic's IDE may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures!''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +{{PageDescription}} +* Undeclared variables with no type suffix are of type [[SINGLE]] by default. +* {{Parameter|letter}} (or {{Parameter|range}}) can be from A-Z or any other range, like '''G-M'''. +* You can also use commas for specific undefined variable first letters. +* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not affected by [[DEFSNG]]. +* [[DEFSNG]] sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''Example:'' DEFSNG A-D, S +==QBasic/QuickBASIC== +* QBasic's IDE would add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64 (like QBasic) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures. -''See also:'' -* [[DEFINT]], [[DEFDBL]], [[DEFLNG]], [[DEFSTR]] +{{PageExamples}} +{{CodeStart}} +{{Cl|DEFSNG}} A, F-H, M + +'With the above, all variables with names starting with A, F, G, H and M +'will be of type SINGLE, unless they have a type suffix +'indicating another type or they are {{Cl|DIM|dimensioned}} differently +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[DEFDBL]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]] * [[_DEFINE]] diff --git a/internal/help/DEFSTR.txt b/internal/help/DEFSTR.txt index fddd043a9..d0c1f94b6 100644 --- a/internal/help/DEFSTR.txt +++ b/internal/help/DEFSTR.txt @@ -1,23 +1,39 @@ -The '''DEFSTR''' statement defines all designated undefined variables AS [[STRING]] variables instead of the [[SINGLE]] type default. +The [[DEFSTR]] statement defines all variables with names starting with the specified letter (or letter range) AS [[STRING]] variables instead of the [[SINGLE]] type default. + + +==Legacy support== +* '''DEF''' statements ([[DEFDBL]], [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFSTR]]) were used when storage space was a concern in older computers, as their usage could save up typing. Instead of {{InlineCode}}'''DIM a AS STRING, a2 AS STRING, a3 AS STRING'''{{InlineCodeEnd}}, simply having {{InlineCode}}'''DEFSTR A'''{{InlineCodeEnd}} in the code before using variables starting with letter '''A''' would do the same job. +* '''For clarity, it is recommended to declare variables with meaningful names'''. {{PageSyntax}} -:: '''DEFSTR ''letter'''''[-''range''] +: [[DEFSTR]] {{Parameter|letter}}[-{{Parameter|range}}], {{Parameter|letter2}}[-{{Parameter|range2}}], [...] - -* The variable starting letters can be from A-Z or any other range. +{{PageDescription}} +* {{Parameter|letter}} (or {{Parameter|range}}) can be from A-Z or any other range, like '''G-M'''. * You can also use commas for specific undefined variable first letters. -* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not defined otherwise. -* DEFSTR sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''Qbasic's IDE may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures!''' +* Variables [[DIM]]ensioned as another variable type or that use type suffixes are not affected by [[DEFSTR]]. +* [[DEFSTR]] sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* '''Warning: QBasic keyword names can only be used as string variable names when they are followed by the string type suffix ($).''' -''Example:'' DEFSTR A-S, Z +==QBasic/QuickBASIC== +* QBasic's IDE would add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64 (like QBasic) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures. -''See also:'' -* [[DEFINT]], [[DEFLNG]], [[DEFSNG]], [[DEFDBL]] +{{PageExamples}} +{{CodeStart}} +{{Cl|DEFSTR}} A, F-H, M + +'With the above, all variables with names starting with A, F, G, H and M +'will be of type STRING, unless they have a type suffix +'indicating another type or they are {{Cl|DIM|dimensioned}} differently +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[DEFSNG]], [[DEFLNG]], [[DEFINT]], [[DEFDBL]] * [[_DEFINE]] diff --git a/internal/help/DEF_FN.txt b/internal/help/DEF_FN.txt index a7c18f5d8..c99efa378 100644 --- a/internal/help/DEF_FN.txt +++ b/internal/help/DEF_FN.txt @@ -1,3 +1,9 @@ +'''This page is maintained for historic purposes. The keyword is not supported in QB64. Create functions using [[FUNCTION]]. If older code contains ''DEF FN'' functions, they must be adapted to be compiled with QB64.''' + + +---- + + The '''DEF FN''' statement defines a non-recursive function in the main module that can use the module's variable values. @@ -8,25 +14,28 @@ The '''DEF FN''' statement defines a non-recursive function in the main module t ::[{{Parameter|statements}}] ::[[DEF FN|FN]]{{Parameter|name}} = {{Parameter|expression}} ::[{{Parameter|statements}}] -:END DEF +:'''END DEF''' {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * {{Parameter|name}} is the name of the function. * {{Parameter|parameterList}} is a comma-separated list of one or more parameters, similar to [[SUB]] and [[FUNCTION]] statements. * {{Parameter|expression}} is any numerical or string value to return from the function. * Function can be created anywhere in a module. Not in [[SUB]] procedures. -* Function can NOT be defined in recursive(repeated) parts of a program. Declare it once only! +* Function must be defined only once and the definition cannot be in recursive (repeated) parts of a program. * Function returns should be assigned to a variable when an alteration to the return value is necessary. -* Function references should only be made AFTER the declaration. -* Multi-line function definitions MUST end with '''END DEF'''. +* Function references should only be made after the declaration. +* Multi-line function definitions must end with '''END DEF'''. * To leave a DEF Fn function early use '''EXIT DEF'''. * This type of function can share values in module level code. To keep values local to the procedure use [[STATIC]]. -* Parameters cannot be from arrays, records or fixed length strings! -* Fn must prefix the function name inside of the procedure and in a call. -* Other variable names or procedures cannot begin with FN or fn in Qbasic! -* Qbasic Help recommends creating real [[FUNCTION]]s over DEF FN functions because of the above limitations. +* Parameters cannot be from arrays, records or fixed length strings. +* ''Fn'' must prefix the function name inside of the procedure and in a call. + + +==QBasic/QuickBASIC== +* Other variable names or procedures cannot begin with FN or fn in QBasic. +* QBasic Help recommends creating real [[FUNCTION]]s over DEF FN functions because of the above limitations. {{PageExamples}} diff --git a/internal/help/DEF_SEG.txt b/internal/help/DEF_SEG.txt index fcbc53e17..e0e3c4553 100644 --- a/internal/help/DEF_SEG.txt +++ b/internal/help/DEF_SEG.txt @@ -1,19 +1,24 @@ -'''DEF SEG''' is used to define the area in memory to access QB64's emulated conventional memory. +[[DEF SEG]] is used to define the area in memory to access QB64's emulated conventional memory. + + +==Legacy support== +* '''QB64 implements memory access using [[_MEM]] and related functions. For that reason, [[DEF SEG]] isn't recommended practice anymore and is supported to maintain compatibility with legacy code.''' {{PageSyntax}} -:: DEF SEG [=][{segment|VARSEG(variable}] +: [[DEF SEG]] [=][{segment|VARSEG(variable}] +{{PageDescription}} * Used to set the pointer to a memory area of a variable/array or register. * [[PEEK]] and [[POKE]] require a segment memory address (often just 0) without using VARSEG. * Important segments using [[PEEK]] and [[POKE]] include &HB800 (text segment) and &HA000 (graphics segment). * [[BSAVE]] and [[BLOAD]] require a VARSEG reference to the grahic array(0 index) used. -* ALWAYS use DEF SEG when the procedure is completed to reset the segment to Qbasic's default value! -* '''Warning: DEF SEG, VARSEG , VARPTR, PEEK or POKE access QB64's emulated 16 bit conventional memory block!''' -: '''It is highly recommended that QB64's [[_MEM]] memory system be used to avoid running out of memory.''' - +* Always use DEF SEG when the procedure is completed, in order to reset the segment to QBasic's default value. +* [[DEF SEG]], [[VARSEG]], [[VARPTR]], [[PEEK]] and [[POKE]] access QB64's emulated 16 bit conventional memory block. '''It is highly recommended to use QB64's [[_MEM]] memory system to avoid running out of memory.''' +<!-- +{{PageExamples}} ''Example:'' In a Qbasic(ONLY) file delete, '''SEG''' forces the parameter to be passed as a far pointer. {{CodeStart}} '' '' {{Cl|CONST}} file = "trashme.tmp" 'example temporary file name to delete @@ -55,7 +60,7 @@ filename = file + {{Cl|CHR$}}(0) 'create zero string name for DOS {{Cl|END}} '' '' {{CodeEnd}} {{small|Code by Michael Calkins as Public Domain(2011)}} - +--> ''See also:'' * [[DEF SEG = 0]] diff --git a/internal/help/DIM.txt b/internal/help/DIM.txt index 35f5de816..7e1072d5b 100644 --- a/internal/help/DIM.txt +++ b/internal/help/DIM.txt @@ -1,41 +1,43 @@ -The '''DIM''' statement is used to [[_DEFINE|define]] a variable or a list of variable types or dimension [[$STATIC]] or [[$DYNAMIC]] [[Arrays]]. +The [[DIM]] statement is used to declare a variable or a list of variables as a specified data type or to dimension [[$STATIC]] or [[$DYNAMIC]] [[Arrays|arrays]]. {{PageSyntax}} -::::''Syntax 1:'' [[DIM]] [{{KW|SHARED}}] ''variable''[{suffix| {{KW|AS}} ''type''}] [, ''variable2''...]] +::''Syntax 1:'' [[DIM]] [{{KW|SHARED}}] ''variable''[{suffix| {{KW|AS}} ''type''}] [, ''variable2''...]] -::::''Syntax 2:'' [[DIM]] [{{KW|SHARED}}] ''Array(lowest% [{{KW|TO}}) highest%])''[{suffix| {{KW|AS}} ''type''}] [, ''variable2''...] +::''Syntax 2:'' [[DIM]] [{{KW|SHARED}}] ''array(lowest% [{{KW|TO}}) highest%])''[{suffix| {{KW|AS}} ''type''}] [, ''variable2''...] -:::'' '''QB64''' Syntax:'' [[DIM]] [{{KW|SHARED}}] ''variable''[{suffix| {{KW|AS}} [{{KW|_UNSIGNED}}] ''type''}] [, ''variable2''...] +:'' '''QB64''' Syntax:'' [[DIM]] [{{KW|SHARED}}] ''variable''[{suffix| {{KW|AS}} [{{KW|_UNSIGNED}}] ''type''}] [, ''variable2''...] -* Sets the [[INTEGER]] range of elements(indices) of a [[STATIC]] array. If only one number is used, the [[LBOUND|lowest boundary]] is 0. -* When used before an array is dimensioned, [[OPTION BASE]] 1 can set the array's default [[LBOUND|lower boundary]] to 1. +{{PageDescription}} +* Sets the [[INTEGER]] range of elements (indices) of a [[STATIC]] array. If only one number is used, the [[LBOUND|lowest boundary]] is 0 by default. +* When used before an array is dimensioned, '''[[OPTION BASE]] 1''' can set the default [[LBOUND|lower boundary]] of arrays to 1. * DIM [[SHARED]] shares variable values with sub-procedures without passing the value in a parameter. -* Uses the [[AS]] keyword to define a variable or array ''type'' [[AS]]... -** [[INTEGER]] or use variable suffix '''%''' -** [[LONG]] or use variable suffix '''&''' -** [[SINGLE]] or use variable suffix '''!''' or no suffix by default -** [[DOUBLE]] or use variable suffix '''#''' -** [[STRING]] or use variable suffix '''$'''. An AS multiplier can set the string [[LEN|length]]. {{text|EX: DIM ''variable'' AS STRING * 8|green}} +* Use the [[AS]] keyword to define a variable or array ''type'' [[AS]]... +** [[INTEGER]] (or use variable suffix '''%''') +** [[LONG]] (or use variable suffix '''&''') +** [[SINGLE]] (or use variable suffix '''!''' or no suffix by default) +** [[DOUBLE]] (or use variable suffix '''#''') +** [[STRING]] (or use variable suffix '''$'''). An AS multiplier can set the string [[LEN|length]]. Ex: {{InlineCode}}DIM ''variable'' AS STRING * 8{{InlineCodeEnd}} * '''QB64''' variable types: -** [[_BIT]] or use variable suffix '''`'''. An AS multiplier can be used for multiple bits. {{text|EX: DIM ''variable'' AS _BIT * 8|green}} -** [[_BYTE]] or use variable suffix '''%%''' -** [[_INTEGER64]] or use variable suffix '''&&''' -** [[_FLOAT]] or use variable suffix '''##''' -** [[_OFFSET]] or use variable suffix '''%&''' -** DIM AS [[_MEM]] only! Does not have a variable type suffix +** [[_BIT]] (or use variable suffix '''`'''). An AS multiplier can be used for multiple bits. Ex: {{InlineCode}}DIM ''variable'' AS _BIT * 8{{InlineCodeEnd}} +** [[_BYTE]] (or use variable suffix '''%%''') +** [[_INTEGER64]] (or use variable suffix '''&&''') +** [[_FLOAT]] (or use variable suffix '''##''') +** [[_OFFSET]] (or use variable suffix '''%&''') +** DIM AS [[_MEM]] (the _MEM type has no type suffix). * '''Note: When a variable has not been defined or has no type suffix, the value defaults to [[SINGLE]].''' -* When the [[$DYNAMIC]] metacommand or [[REDIM]] is used, array element sizes are changeable(not [[$STATIC]]). +* When the [[$DYNAMIC]] metacommand or [[REDIM]] is used, array element sizes are changeable (not [[$STATIC]]). * Use [[REDIM]] instead of DIM to dimension arrays as dynamic without the {{KW|$DYNAMIC}} metacommand. -* Use [[REDIM]] [[_PRESERVE]] in QB64 to retain previous array values when changing the size of an array. -* [[REDIM]] [[_PRESERVE]] cannot change the number of array dimensions! An [[ERROR Codes|error]] will occur! -* [[$DYNAMIC|Dynamic]] arrays MUST be [[REDIM]]ensioned if [[ERASE]] or [[CLEAR]] are used as the arrays are completely removed. -* All numerical variable types '''except''' {{KW|SINGLE}}, {{KW|DOUBLE}} and {{KW|_FLOAT}} can be dimensioned as [[_UNSIGNED]](suffix ~) or positive only. -* '''NOTE: Many Qbasic keyword variable names CAN be used with a [[STRING]] suffix($) ONLY! You CANNOT use them without the suffix, use a numerical suffix or use DIM, [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements!''' -* '''Warning! Do not use negative array Upper bound index values as OS access or "Out of Memory" [[ERROR Codes|errors]] will occur!''' +* Use [[REDIM]] [[_PRESERVE]] in '''QB64''' to retain previous array values when changing the size of an array. +* [[REDIM]] [[_PRESERVE]] cannot change the number of array dimensions. An [[ERROR Codes|error]] will occur. +* [[$DYNAMIC|Dynamic]] arrays MUST be [[REDIM]]ensioned if [[ERASE]] or [[CLEAR]] are used, as the arrays are completely removed. +* All numerical variable types '''except''' {{KW|SINGLE}}, {{KW|DOUBLE}} and {{KW|_FLOAT}} can be dimensioned as [[_UNSIGNED]] (suffix ~) or positive only. +* '''NOTE:''' Many QBasic keyword variable names can be used with a [[STRING]] suffix ($). You cannot use them without the suffix, use a numerical suffix or use ''DIM, [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]]'' statements. '''Although possible, it's recommended to avoid using reserved names.''' +* '''Warning: Do not use negative array upper bound index values, or OS access or "Out of Memory" [[ERROR Codes|errors]] will occur.''' +{{PageExamples}} ''Example 1:'' Defines Qt variable as a one byte fixed length string. {{CodeStart}} {{Cl|DIM}} Qt {{Cl|AS}} {{Cl|STRING}} * 1 @@ -62,7 +64,7 @@ The '''DIM''' statement is used to [[_DEFINE|define]] a variable or a list of va {{CodeEnd}} -''Example 6:'' QB64 is more flexible than Qbasic when it comes to "Duplicate Definition" errors. The following code does not error: +''Example 6:'' QB64 is more flexible than QBasic when it comes to "Duplicate Definition" errors. The following code does not error: {{CodeStart}} '' '' x = 1 'x is a {{Cl|SINGLE}} variable {{Cl|PRINT}} x @@ -89,6 +91,7 @@ x = 1 'x is a {{Cl|SINGLE}} variable * [[DEFINT]], [[DEFSNG]], [[DEFLNG]], [[DEFDBL]], [[DEFSTR]] * [[Mathematical Operations]], [[Arrays]] * [[Variable Types]] +* [[OPTION _EXPLICIT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/DIR$.txt b/internal/help/DIR$.txt index 3f8d5eab9..6fc694ff1 100644 --- a/internal/help/DIR$.txt +++ b/internal/help/DIR$.txt @@ -1,61 +1,52 @@ -The '''DIR$''' function below is '''NOT A QB64 FUNCTION!''' This page supplies equivalent QB code: +{{DISPLAYTITLE:_DIR$}} +The [[_DIR$]] function returns common paths in '''Windows''' only such as My Documents, My Pictures, My Music, Desktop. {{PageSyntax}} -::: filename$ = '''DIR$('''{filespec$|""}''')''' +: {{Parameter|d$}} = [[_DIR$]]("{{Parameter|folderspecification}}") -The DIR$ function used in PDS(7.1) returns a filename or a list when more than one exist. The file spec can use a path and/or wildcards. -{{CodeStart}} '' '' -{{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} 2 - {{Cl|PRINT}} - {{Cl|LINE INPUT}} "Enter a file spec: ", spec$ - file$ = DIR$(spec$) 'use a file spec ONCE to find the last file name listed - {{Cl|PRINT}} DIRCount%, file$, 'function can return the file count using {{Cl|SHARED}} variable - {{Cl|IF...THEN|IF}} DIRCount% > 1 {{Cl|THEN}} - DO - K$ = {{Cl|INPUT$}}(1) - file$ = DIR$("") ''''use an empty string parameter to return a list of files!''' - {{Cl|PRINT}} file$, - {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|LEN}}(file$) = 0 'file list ends with an empty string - {{Cl|END IF}} -{{Cl|NEXT}} +{{Parameters}} +* ''folderspecification'' may be "desktop", "download", "documents", "music", "video", "pictures", "appdata", "program data", "local data". +* Some variation is accepted for the folder specification: +:: MY DOCUMENTS, TEXT, DOCUMENT, DOCUMENTS, DOWNLOAD, DOWNLOADS +:: MY MUSIC, MUSIC, AUDIO, SOUND, SOUNDS +:: MY PICTURES, PICTURE, PICTURES, IMAGE, IMAGES, PHOTO, PHOTOS, DCIM, CAMERA, CAMERA ROLL +:: MY VIDEOS, VIDEO, VIDEOS, MOVIE, MOVIES, +:: DATA, APPDATA, APPLICATION DATA, PROGRAM DATA, LOCAL DATA, LOCALAPPDATA, LOCAL APPLICATION DATA, LOCAL PROGRAM DATA -{{Cl|END}} -{{Cl|FUNCTION}} DIR$ (spec$) -{{Cl|CONST}} TmpFile$ = "DIR$INF0.INF", ListMAX% = 500 'change maximum to suit your needs -{{Cl|SHARED}} DIRCount% 'returns file count if desired -{{Cl|STATIC}} Ready%, Index%, DirList$() -{{Cl|IF...THEN|IF}} {{Cl|NOT}} Ready% {{Cl|THEN}} {{Cl|REDIM}} DirList$(ListMAX%): Ready% = -1 '{{Cl|DIM}} array first use -{{Cl|IF...THEN|IF}} spec$ > "" {{Cl|THEN}} 'get file names when a spec is given - {{Cl|SHELL}} {{Cl|_HIDE}} "DIR " + spec$ + " /b > " + TmpFile$ - Index% = 0: DirList$(Index%) = "": ff% = {{Cl|FREEFILE}} - {{Cl|OPEN}} TmpFile$ {{Cl|FOR...NEXT|FOR}} {{Cl|APPEND}} {{Cl|AS}} #ff% - size& = {{Cl|LOF}}(ff%) - {{Cl|CLOSE}} #ff% - {{Cl|IF...THEN|IF}} size& = 0 {{Cl|THEN}} {{Cl|KILL}} TmpFile$: {{Cl|EXIT FUNCTION}} - {{Cl|OPEN}} TmpFile$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #ff% - {{Cl|DO...LOOP|DO}} {{Cl|WHILE}} {{Cl|NOT}} {{Cl|EOF}}(ff%) {{Cl|AND (boolean)|AND}} Index% < ListMAX% - Index% = Index% + 1 - {{Cl|LINE INPUT (file statement)|LINE INPUT}} #ff%, DirList$(Index%) - {{Cl|LOOP}} - DIRCount% = Index% '{{Cl|SHARED}} variable can return the file count - {{Cl|CLOSE}} #ff% - {{Cl|KILL}} TmpFile$ -{{Cl|ELSE}} {{Cl|IF...THEN|IF}} Index% > 0 {{Cl|THEN}} Index% = Index% - 1 'no spec sends next file name -{{Cl|END IF}} -DIR$ = DirList$(Index%) -{{Cl|END FUNCTION}} '' '' +{{PageDescription}} +* The path returned ends with a backslash (Windows). +* A nonexistent folder specification usually defaults to the Desktop folder path. +* In Linux and macOS the function always returns '''"./"''' + + +{{PageExamples}} +Example: Displaying default paths in Windows only. +{{CodeStart}}{{Cl|PRINT}} "DESKTOP=" + _DIR$("desktop") +{{Cl|PRINT}} "DOWNLOADS=" + {{Cl|_DIR$}}("download") +{{Cl|PRINT}} "DOCUMENTS=" + {{Cl|_DIR$}}("my documents") +{{Cl|PRINT}} "PICTURES=" + {{Cl|_DIR$}}("pictures") +{{Cl|PRINT}} "MUSIC=" + {{Cl|_DIR$}}("music") +{{Cl|PRINT}} "VIDEO=" + {{Cl|_DIR$}}("video") +{{Cl|PRINT}} "APPLICATION DATA=" + {{Cl|_DIR$}}("data") +{{Cl|PRINT}} "LOCAL APPLICATION DATA=" + {{Cl|_DIR$}}("local application data" {{CodeEnd}} -{{small|Code by Ted Weissgerber}} -:''Explanation:'' The function will verify that a file exists (even if it is empty) by returning it's name or it returns an empty string if no file exists. It can return a list of file names by using an empty string parameter("") after sending a wildcard spec to get the first file name. The number of file names found is returned by using the SHARED variable, '''DIRCount%'''. Unlike the PDS DIR$ function, '''it MUST use an empty string parameter until QB64 supports optional parameters!''' The function does NOT delete empty files. +{{OutputStart}}DESKTOP=C:\Documents and Settings\Administrator\Desktop\ +DOWNLOADS=C:\Documents and Settings\Administrator\Downloads\ +DOCUMENTS=C:\Documents and Settings\Administrator\My Documents\ +PICTURES=C:\Documents and Settings\Administrator\My Documents\My Pictures\ +MUSIC=C:\Documents and Settings\Administrator\My Documents\My Music\ +VIDEO=C:\Documents and Settings\Administrator\My Documents\My Videos\ +APPLICATION DATA=C:\Documents and Settings\Administrator\Application Data\ +LOCAL APPLICATION DATA=C:\Documents and Settings\Administrator\Local Settings\Application Data\ +{{OutputEnd}} -''See also:'' -* [[FILES]] -* [[KILL]] -* [[SHELL]] - +{{PageSeeAlso}} +* [[_CWD$]] +* [[_STARTDIR$]] + {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/DO...LOOP.txt b/internal/help/DO...LOOP.txt index 7e1b75339..e94747aaf 100644 --- a/internal/help/DO...LOOP.txt +++ b/internal/help/DO...LOOP.txt @@ -2,36 +2,37 @@ {{PageSyntax}} +''Syntax 1:'' :'''[[DO]]''' [{{{KW|WHILE}}|{{KW|UNTIL}}} condition] -:. -:. -:. +:: ''{code}'' +:: ⋮ :'''[[LOOP]]''' + +''Syntax 2:'' :'''[[DO]]''' -:. -:. -:. +:: ''{code}'' +:: ⋮ :'''[[LOOP]]''' [{{{KW|WHILE}}|{{KW|UNTIL}}} condition] {{PageDescription}} -* DO UNTIL or DO WHILE used with LOOP. The DO will evaluate the condition before running the loop code: -::[[UNTIL]] checks if the condition is False each time before running code. -::[[WHILE]] checks if the condition is True each time before running code. -* DO used with LOOP UNTIL or LOOP WHILE. The loop code will run at least once: -::[[UNTIL]] checks if the condition is False before running loop code again. -::[[WHILE]] checks if the condition is True before running loop code again. -* NOTE: You cannot use a condition after both the DO and LOOP statements at the same time! -* Use '''[[EXIT]] DO''' to exit a DO loop within the loop code. -* If a loop never meets an exit condition requirement, it will never stop! -* '''Condition expressions are required after WHILE or UNTIL or QB64 will return a compiler error!''' +* '''DO UNTIL or DO WHILE used with LOOP''': The condition is evaluated before running the loop code. +::[[UNTIL]] checks if the condition is false each time before running code. +::[[WHILE]] checks if the condition is true each time before running code. +* '''DO used with LOOP UNTIL or LOOP WHILE''': The code block will run at least once: +::[[UNTIL]] checks if the condition is false before running loop code again. +::[[WHILE]] checks if the condition is true before running loop code again. +* NOTE: You cannot use a condition after both the DO and LOOP statements at the same time. +* Use '''[[EXIT]] DO''' to exit a loop block even before the condition is met. +** If you don't specify a condition, you must exit the loop block manually using '''[[EXIT]] DO'''. +* If a loop never meets an exit condition requirement, it will never stop. {{Template:RelationalTable}} - +{{PageExamples}} ''Example 1:'' Using WHILE to clear the keyboard buffer. {{CodeStart}} diff --git a/internal/help/DOUBLE.txt b/internal/help/DOUBLE.txt index 5ac567341..03ff8b521 100644 --- a/internal/help/DOUBLE.txt +++ b/internal/help/DOUBLE.txt @@ -1,20 +1,23 @@ -'''DOUBLE''' type floating point numerical values use 8 bytes per value. +[[DOUBLE]] type floating point numerical values use 8 bytes per value. {{PageSyntax}} -:: [[DIM]] ''variable'' AS DOUBLE +: [[DIM]] {{Parameter|variable}} [[AS]] [[DOUBLE]] {{PageDescription}} * Literal or variable values can range up to 15 decimal point places. -* Qbasic variable suffix type is #. The IDE may add the suffix after literal values. -* Results of mathematical calculations may be approximate or slow in Quickbasic 4.5. -* Use DOUBLE and [[_FLOAT]] variables SPARINGLY! They use a lot of program memory. +* The variable suffix type is '''#'''. +* Use DOUBLE and [[_FLOAT]] variables sparingly as they use a lot of program memory. * Values returned may be expressed using exponential or [[scientific notation]] using '''E''' for SINGLE or '''D''' for DOUBLE precision. -* Floating decimal point numerical values cannot be [[_UNSIGNED]]! +* Floating decimal point numerical values cannot be [[_UNSIGNED]]. * Values can be converted to 8 byte [[ASCII]] string values using [[_MKD$]] and back with [[_CVD]]. * '''When a variable has not been defined or has no type suffix, the value defaults to [[SINGLE]].''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' + + +==QBasic/QuickBASIC== +* Results of mathematical calculations may be approximate or slow in QuickBASIC 4.5. {{PageSeeAlso}} diff --git a/internal/help/DRAW.txt b/internal/help/DRAW.txt index 1e6afa4b8..bda185388 100644 --- a/internal/help/DRAW.txt +++ b/internal/help/DRAW.txt @@ -1,44 +1,45 @@ -:::The '''DRAW''' graphics statement uses a [[STRING]] expression to draw lines on the screen. - +The [[DRAW]] statement uses a [[STRING]] expression to draw lines on the screen. {{PageSyntax}} -:: '''DRAW''' draw_string$ +: [[DRAW]] {{Parameter|drawString$}} -* The draw string can be a draw value in quotation marks or a [[STRING]] variable using DRAW function letters. -* DRAW starting coordinates can be set using [[PSET]], [[PRESET]], [[CIRCLE]] or [[LINE]] ending positions. [[PSET]] or [[PRESET]] colors pass too. +{{PageDescription}} +* The {{Parameter|drawString$}} can be [[DRAW]] instructions in quotation marks or a [[STRING]] variable using [[DRAW]] instructions. +* [[DRAW]] starting coordinates can be set using [[PSET]], [[PRESET]], [[CIRCLE]] or [[LINE]] ending positions. * Other graphic objects can be located at or relative to the last DRAW position using [[STEP]]. -* DRAW can adopt colors from other graphics objects such as [[PSET]], [[LINE]] and [[CIRCLE]] statements. +* [[DRAW]] can inherit colors from other graphic statements such as [[PSET]], [[LINE]] and [[CIRCLE]]. * Draw strings use letters followed by the number of pixels to move, an angle, coordinate or a color value. -* Draw strings are flexible with spacing. '''Spacing is not required!''' DRAW will look for a number value after a valid letter. -* DRAW statements are not Case sensitive. Use upper or lower case. -:* "'''B'''" (Blind) before a line move designates that the line move will be hidden. Use to offset from a "P" or [[PAINT]] border. -:* "'''C''' n" designates the color attribute or [[_RGB]] [[STR$|string]] numerical color value to be used in the draw statement immediately after. -:* "'''M''' x, y" can move to another coordinate area of the screen. When a + or - sign is used before a coordinate, -::it is a relative coordinate move similar to using the [[STEP]] graphics keyword. DRAW "M+=" + [[VARPTR$]](variable%) -:* "'''N'''" before a line move designates that the drawn line will return to the line start position. Saves moves! -:* "'''P''' f [, b]" is used to [[PAINT|paint]] enclosed objects. f denotes the fill color and b the border color if needed. -:* "'''S''' n" changes the pixel move size of the lines. Default is 4(1 pixel) minimum. "S8" would double the pixel line moves. -:* "'''X'''" + [[VARPTR$]](value) can draw another substring. +* Draw strings are flexible with spacing. '''Spacing is not required.''' [[DRAW]] will look for a number value after a valid letter. +* DRAW statements are not case sensitive. +** "'''B'''" (blind) before a line move designates that the line move will be hidden. Use to offset from a "P" or [[PAINT]] border. +** "'''C''' n" designates the color attribute or [[_RGB]] [[STR$|string]] numerical color value to be used in the draw statement immediately after. +** "'''M''' x, y" can move to another coordinate area of the screen. When a + or - sign is used before a coordinate, it is a relative coordinate move similar to using the [[STEP]] graphics keyword. DRAW "M+=" + [[VARPTR$]](variable%) +** "'''N'''" before a line move designates that the graphic cursor will return to the starting position after the line is drawn. +** "'''P''' f [, b]" is used to [[PAINT|paint]] enclosed objects. f denotes the fill color and b the border color, if needed. +** "'''S''' n" changes the pixel move size of the lines. Default is 4 (1 pixel) minimum. "S8" would double the pixel line moves. +** "'''X'''" + [[VARPTR$]](value) can draw another substring. * Certain letter designations create line moves on the SCREEN. Each move is followed by the number of pixels: -:* "'''D''' n" draws a line vertically DOWN n pixels. -:* "'''E''' n" draws a diagonal / line going UP and RIGHT n pixels each direction. -:* "'''F''' n" draws a diagonal \ line going DOWN and RIGHT n pixels each direction. -:* "'''G''' n" draws a diagonal / LINE going DOWN and LEFT n pixels each direction. -:* "'''H''' n" draws a diagonal \ LINE going UP and LEFT n pixels each direction. -:* "'''L''' n" draws a line horizontally LEFT n pixels. -:* "'''R''' n" draws a line horizontally RIGHT n pixels. -:* "'''U''' n" draws a line vertically UP n pixels. +** "'''D''' n" draws a line vertically DOWN n pixels. +** "'''E''' n" draws a diagonal / line going UP and RIGHT n pixels each direction. +** "'''F''' n" draws a diagonal \ line going DOWN and RIGHT n pixels each direction. +** "'''G''' n" draws a diagonal / LINE going DOWN and LEFT n pixels each direction. +** "'''H''' n" draws a diagonal \ LINE going UP and LEFT n pixels each direction. +** "'''L''' n" draws a line horizontally LEFT n pixels. +** "'''R''' n" draws a line horizontally RIGHT n pixels. +** "'''U''' n" draws a line vertically UP n pixels. -* Angles are used to rotate ALL draw moves following their use. U could become a down move or even rotate. -:* "'''A''' n" can use values of 1 to 3 to rotate up to 3 90 degree(270) angles. -:* '''TA''' n" can use any n angle from -360 to 0 to 360 to rotate a DRAW (Turn Angle). "TA0" resets to normal. -:* When [[VARPTR$]] is used DRAW functions such as '''TA''' angles use an equal sign: "TA=" + VARPTR$(angle%) -* '''DRAW can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only!''' +* Angles are used to rotate all subsequent draw moves. +** "'''A''' n" can use values of 1 to 3 to rotate up to 3 90 degree(270) angles. +** '''TA''' n" can use any n angle from -360 to 0 to 360 to rotate a DRAW (Turn Angle). "TA0" resets to normal. +** When [[VARPTR$]] is used, DRAW functions such as '''TA''' angles use an equal sign: "TA=" + VARPTR$(angle%) +* The graphic cursor is set to the center of the program window on program start for [[STEP]] relative coordinates. +* '''DRAW can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only.''' +{{PageExamples}} ''Example 1:'' Placing an octagon shape DRAW across the the screen using PSET. {{CodeStart}} '' '' @@ -67,7 +68,6 @@ NEXT '' '' {{CodeEnd}} - ''Explanation:'' To place 12 circles in a circle each move is 30 degrees. PSET sets the center of the circular path every loop. TA moves counter-clockwise with positive degree angles. Once TA sets the angle a blind Up move is at that angle. The hour circles use the end point of the blind line as centers using the STEP relative coordinates of 0. After the circles are drawn, a draw "P" string paints the circle centers. DRAW paint strings use the last coordinate position also. @@ -85,8 +85,7 @@ LOOP {{CodeEnd}} - -''Explanation:'' The degrees to move from the original UP line move is calculated by dividing 360/60 seconds in a full rotation. That value of 6 is made negative to use TA correctly and multiplied by the [[VAL]]ue of seconds from the TIME$ function. The degree angle is converted by [[STR$]] to a string and added to the DRAW string using the [[STRING]] '''concatenation +''' operator. DO NOT USE SEMICOLONS to create DRAW strings! Once the second hand is placed on the screen, a loop waits for the second value to change. It then erases the hand and it repeats the process again. +''Explanation:'' The degrees to move from the original UP line move is calculated by dividing 360/60 seconds in a full rotation. That value of 6 is made negative to use TA correctly and multiplied by the [[VAL]]ue of seconds from the TIME$ function. The degree angle is converted by [[STR$]] to a string and added to the DRAW string using the [[STRING]] '''concatenation +''' operator. Do not use semicolons to create DRAW strings. Once the second hand is placed on the screen, a loop waits for the second value to change. It then erases the hand and it repeats the process again. ''Example 4:'' Creating digital displays using DRAW format strings to create the LED segments. (See [[SELECT CASE|SELECT EVERYCASE]] example 5) @@ -159,7 +158,7 @@ k = {{Cl|_RGB}}(80, 255, 80) : ''Explanation:'' DRAW strings will ignore spaces between letters and numbers so string trimming is not necessary. -''See also:'' +{{PageSeeAlso}} * [[LINE]], [[PSET]], [[PRESET]], [[CIRCLE]] * [[PAINT]], [[SCREEN (statement)|SCREEN]] * [[COLOR]], [[PLAY]] diff --git a/internal/help/ELSE.txt b/internal/help/ELSE.txt index f98b18ab7..40bd5f49f 100644 --- a/internal/help/ELSE.txt +++ b/internal/help/ELSE.txt @@ -1,24 +1,32 @@ -'''ELSE''' is used in [[IF...THEN]] or [[SELECT CASE]] statements to offer an alternative to other conditional statements. +[[ELSE]] is used in [[IF...THEN]] or [[SELECT CASE]] statements to offer an alternative to other conditional statements. {{PageSyntax}} -:: IF condition <> 0 THEN evaluation = -1 [[ELSE]] evaluation = 0 +''Single-line syntax:'' +: [[IF]] {{Parameter|condition}} [[THEN]] ''{code}'' [[ELSE]] ''{alternative-code}'' -''Block {{PageSyntax}} -:: IF condition > 0 THEN -:: evaluation = -1 -:: [[ELSEIF]] condition < 0 THEN evaluation = -1 -:: [[ELSE]] evaluation = 0 -:: [[END IF]] +''Block syntax:'' +: [[IF]] {{Parameter|condition}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSEIF]] {{Parameter|condition2}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSE]] +:: ''{alternative-code}'' +:: ⋮ +: [[END IF]] -* ELSE is used in a IF block statement to cover any remaining conditions not covered in the block by IF or [[ELSEIF]]. +{{PageDescription}} +* ELSE is used in a IF block statement to cover any remaining conditions not covered in the main block by IF or [[ELSEIF]]. * [[CASE ELSE]] covers any remaining conditions not covered by the other CASE statements. -* ELSE can also be used as a False comparison to a True IF statement when a condition will only be True or False. +* ELSE can also be used as a false comparison to a true IF statement when a condition will only be true or false. * Other [[IF...THEN]] statements can be inside of an ELSE statement. +{{PageExamples}} ''Example 1:'' One line IF statement {{CodeStart}} @@ -46,7 +54,7 @@ IF a = 3 THEN a = 5 ELSE a = 3 -''See also:'' +{{PageSeeAlso}} * [[ELSEIF]] * [[IF...THEN]] diff --git a/internal/help/ELSEIF.txt b/internal/help/ELSEIF.txt index a7632221a..0be71858b 100644 --- a/internal/help/ELSEIF.txt +++ b/internal/help/ELSEIF.txt @@ -1,17 +1,23 @@ -'''ELSEIF''' is used in a block [[IF...THEN]] statement to offer an alternative condition. +[[ELSEIF]] is used in an [[IF...THEN]] block statement to offer an alternative condition. -''Block'' {{PageSyntax}} -:: IF condition > 0 THEN -:: evaluation = -1 -:: [[ELSEIF]] condition < 0 THEN evaluation = -1 -:: [[ELSE]] evaluation = 0 -:: [[END IF]] +{{PageSyntax}} +: [[IF]] {{Parameter|condition}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSEIF]] {{Parameter|condition2}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSE]] +:: ''{alternative-code}'' +:: ⋮ +: [[END IF]] -* ELSEIF statements REQUIRE a '''separate''' code block line with [[THEN]] for each alternative condition. +{{PageDescription}} +* ELSEIF statements require a '''separate''' code block line with [[THEN]] for each alternative condition. * There can be more than one [[ELSE]] IF statement in a single-line IF statement. -* If there is only ONE possible alternative condition(such as 0 or [[NOT]] 0), then use [[ELSE]] instead. +* If there is only one possible alternative condition (such as 0 or [[NOT]] 0), use [[ELSE]] instead. * If the comparisons are based on multiple conditions being true, it may require many ELSEIF comparisons. ELSE could help cover some of those conditions. * You can use [[SELECT CASE]] when IF blocks have a long list of alterative ELSEIF conditions. @@ -19,6 +25,7 @@ {{Template:RelationalTable}} +{{PageExamples}} ''Example 1:'' IF statement using ELSE IF in one statement line. {{CodeStart}} @@ -40,13 +47,9 @@ END IF -''See also:'' - +{{PageSeeAlso}} *[[ELSE]], [[END IF]] - *[[IF...THEN]] - - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/END.txt b/internal/help/END.txt index cb4ec411a..7970b6236 100644 --- a/internal/help/END.txt +++ b/internal/help/END.txt @@ -1,27 +1,25 @@ -The {{KW|END}} statement terminates a program without an immediate exit or ends a procedure or statement block. +The [[END]] statement terminates a program without an immediate exit or ends a procedure or statement block. {{PageSyntax}} -::: END -::: END [[IF...THEN|IF]] -::: END [[TYPE]] -::: END [[SELECT CASE|SELECT]] -::: END [[SUB]] -::: END [[FUNCTION]] - -QB64 {{PageSyntax}} -::: END [return_code%] -::: END [[DECLARE LIBRARY|DECLARE]] +: [[END]] [{{Parameter|returnCode%}}] +: [[END]] [[IF...THEN|IF]] +: [[END]] [[TYPE]] +: [[END]] [[SELECT CASE|SELECT]] +: [[END]] [[SUB]] +: [[END]] [[FUNCTION]] +: END [[DECLARE LIBRARY|DECLARE]] -* In '''QB64''' END can be followed by a code that can be read in another module using the [[SHELL (function)|_SHELL]] or [[_SHELLHIDE]] function. -* When END is used to end a program a pause and "Press any key to continue..." is displayed at the bottom of the window. -* If the program does not use END or [[SYSTEM]] the program will still end with a pause and display "Press any key to continue...". -* In '''QB64''' [[SYSTEM]] will end the program immediately and close the window. -* The '''QB64''' [[_EXIT (function)]] can block a user's Ctrl + Break key press or click on the window X box until the program is ready. -* When running a Qbasic BAS module from the command line, use [[SYSTEM]] to avoid returning to the [[IDE]]. +{{PageDescription}} +* In '''QB64''', [[END]] can be followed by a code that can be read by another module using the [[SHELL (function)|_SHELL]] or [[_SHELLHIDE]] function (known as [https://blogs.msdn.microsoft.com/oldnewthing/20080926-00/?p=20743 '''errorlevel''']) +* When END is used to end a program, there is a pause and the message "Press any key to continue..." is displayed at the bottom of the program's window. +* If the program does not use END or [[SYSTEM]], the program will still end with a pause and display "Press any key to continue...". +* In '''QB64''', [[SYSTEM]] will end the program immediately and close the window. +* The '''QB64''' [[_EXIT (function)]] can block a user's Ctrl + Break key presses and clicks on the window's close button (X button) until the program is ready to close. +{{PageExamples}} ''Example:'' In QB64 you won't return to the IDE unless you are using it to run or edit the program module. {{CodeStart}} '' '' @@ -41,7 +39,7 @@ Hello world! Press any key to continue... {{OutputEnd}} :''Explanation:''"Hello no one!" isn't returned because the program ended with the END statement no matter what is after that. -:The message "Press any key to continue..." is displayed after the program ends in QB or '''QB64'''. +:The message "Press any key to continue..." is displayed after the program ends, both in QBasic and in '''QB64'''. diff --git a/internal/help/ENVIRON$.txt b/internal/help/ENVIRON$.txt index 9d7c2be84..0a25d03ec 100644 --- a/internal/help/ENVIRON$.txt +++ b/internal/help/ENVIRON$.txt @@ -1,34 +1,33 @@ -The '''ENVIRON$''' function returns a [[STRING]] environmental value from the '''Windows''' PC's environmental settings list. - +The [[ENVIRON$]] function returns a [[STRING]] environmental value from '''Windows'''' environmental settings list. {{PageSyntax}} - -::: setting$ = ENVIRON$({''list_number%''|''systemID$''}) +: {{Parameter|setting$}} = [[ENVIRON$]]({{{Parameter|listIndex%}}|{{Parameter|systemID$}}}) -* The function can use an [[INTEGER]] ''list_number'' order value or [[STRING]] ''systemID$'' parameter. -* ''List_number'' refers to the number order of the environmental list. Returns are not in any particular numerical order. -* ''SystemID'' is the specific [[STRING]] parameter requested. Returns that environmental [[STRING]] setting only: -::* "BLASTER" = current Sound Blaster settings if installed. -::* "COMPUTERNAME" or "USERDOMAIN" = OEM PC serial number or the computer name assigned by owner. -::* "HOMEDRIVE" or "SystemDrive" = Windows root drive, normally C: on single partition drives. -::* "HOMEPATH" = current user's Administrator or the single user's "OWNER" folder path. -::* "OS" = Windows Operating System version. Often WindowsNT these days. -::* "PATH" = full Windows path settings that windows uses to look for file extensions in PATHEXT below. -::* "PATHEXT = Windows extensions used: COM, EXE, BAT, CMD, VBS, VBE, JS, JSE, WSF, WSH, MSC -::* "PROCESSOR_ARCHITECTURE" = x86 for 32 or 64 bit so far. -::* "PROGRAMFILES" = path to Program files folder normally "C:\PROGRAM FILES" -::* "PROMPT" = $P$G normaly on Windows NT. Windows 95 and 98 = "[WIN 98]$P$G" but cannot run QB64! -::* "SYSTEMROOT" or "windir" = path to the Windows folder including the drive letter like "C:\WINDOWS" -::* "TEMP" or "TMP" = path to TEMP folder. "C:\TEMP" or the user specific temp folder on later versions. -::* "USERNAME" = current Administrator name or "OWNER". -: ''Note:'' There are other possible system settings that are not listed or never used on older versions! Run ''Example 1'' -* The OS in Win 9X or ME can be found in the "PROMPT" parameter ID. Returns are limited in Win 9X and ME. -* ''Note:'' '''QB64''' may not return the same environment list as Qbasic or SET does in DOS. - +{{PageDescription}} +* The function can use an [[INTEGER]] {{Parameter|listIndex%}} value or [[STRING]] {{Parameter|systemID$}} parameter. +* {{Parameter|listIndex%}} refers to the number order of the environmental list. Returns are not in any particular numerical order. +* {{Parameter|systemID$}} is the specific [[STRING]] parameter requested. Returns only the specified environmental [[STRING]] setting: +** "BLASTER" = current Sound Blaster settings if installed. +** "COMPUTERNAME" or "USERDOMAIN" = OEM PC serial number or the computer name assigned by owner. +** "HOMEDRIVE" or "SystemDrive" = Windows root drive, normally C: on single partition drives. +** "HOMEPATH" = current user's Administrator or the single user's "OWNER" folder path. +** "OS" = Windows Operating System version. Often WindowsNT in modern computers. +** "PATH" = full path setting that Windows uses to look for file extensions in PATHEXT below. +** "PATHEXT = Windows extensions used: COM, EXE, BAT, CMD, VBS, VBE, JS, JSE, WSF, WSH, MSC +** "PROCESSOR_ARCHITECTURE" = x86 for 32 or 64 bit. +** "PROGRAMFILES" = path to ''Program files'' folder, normally "C:\PROGRAM FILES" +** "PROMPT" = normally "$P$G" on Windows NT. +** "SYSTEMROOT" or "windir" = path to the Windows folder including the drive letter like "C:\WINDOWS" +** "TEMP" or "TMP" = path to TEMP folder. "C:\TEMP" or the user specific temp folder on later versions. +** "USERNAME" = current Administrator name or "OWNER". +: ''Note:'' There are other possible system settings that are not listed or never used on older versions. Run ''Example 1'' below for a complete list in your system. +<!-- Sentence removed for being unclear/needs revision: * The OS in Win 9X or ME can be found in the "PROMPT" parameter ID. Returns are limited in Win 9X and ME. --> +* ''Note:'' '''QB64''' may not return the same environment list as QBasic or SET did in DOS. +{{PageExamples}} ''Example 1:'' Viewing the list of environmental parameter settings using a counter loop like SET does in DOS. {{CodeStart}} '' '' @@ -64,7 +63,7 @@ USERDOMAIN=TED-LAPTOP USERNAME=Ted USERPROFILE=C:\Users\Ted {{OutputEnd}} -:''Note:'' Windows environmental settings are listed alphabetically, 20 at a time. '''QB64 may not read all of them or return an empty string!''' The settings above were returned with SET in DOS. PROMPT returned nothing where SET returned $P$G. +:''Note:'' Windows environmental settings are listed alphabetically, 20 at a time. '''QB64 may not read all of them or may return an empty string.''' The settings above were returned with SET in DOS. PROMPT returned nothing where SET returned $P$G. ''Example 2:'' Creating a shortcut on a user's desktop for QB64.EXE using the program's icon. Must be run in program's folder to work! @@ -114,8 +113,7 @@ Q$ = {{Cl|CHR$}}(34) '=== Write URL Shortcut file info. {{CodeEnd}} {{small|Adapted from code by Dav}} : ''Explanation:'' The SUB program finds the current program's path and user's desktop path. It then creates the shortcut on the desktop with a program icon. The custom icon should be in the program's folder. If an environmental path is not found, the shortcut is placed in the program's folder. The SUB can be added to any program. - -<center>{{Text|'''NOTE:''' A temorary file named PRGMDIR.INF is created and deleted.|darkred}}</center> +:{{Text|'''NOTE:''' A temorary file named PRGMDIR.INF is created and deleted in the example above.}} ''See also:'' diff --git a/internal/help/ENVIRON.txt b/internal/help/ENVIRON.txt index ccf90a0b8..4c65e256c 100644 --- a/internal/help/ENVIRON.txt +++ b/internal/help/ENVIRON.txt @@ -1,22 +1,25 @@ -The '''ENVIRON''' statement is used '''in Windows''' to temporarily set or change an environmental string value. +'''This page is maintained for historic purposes. The keyword is [[Keywords_currently_not_supported_by_QB64|not supported in QB64]]. Reading values is supported with [[ENVIRON$]]. +---- +The [[ENVIRON]] statement is used in DOS/Windows to temporarily set or change an environmental string value. {{PageSyntax}} -:: ENVIRON string_expression$ +: [[ENVIRON]] {{Parameter|stringExpression$}} -* [[Keywords_currently_not_supported_by_QB64]] -* The string expression must include the environmental parameter ID and the setting two ways: -: * Using an = : ENVIRON parameterID=setting -: * Using a space: ENVIRON parameterID setting +{{PageDescription}} +* [[Keywords_currently_not_supported_by_QB64|Not supported in QB64.]] +* The {{Parameter|stringExpression$}} must include the environmental parameter ID and the setting: +** Using an '''=''' sign: [[ENVIRON]] "parameterID=setting" +** Using a space: [[ENVIRON]] "parameterID setting" * If the parameter ID did not previously exist in the environmental string table, it is appended to the end of the table. * If a parameter ID did exist, it is deleted and the new value is appended to end of the list. -* DOS discards any changes when your program ends so the program must set them when run! +* DOS discards any changes when your program ends so the program must set them when run. * '''WARNING:''' The amount of space in a environmental table is limited and may create memory errors. -''See also:'' +{{PageSeeAlso}} * [[ENVIRON$]] * [[Windows Environment]] diff --git a/internal/help/EOF.txt b/internal/help/EOF.txt index 9f9a0c3c2..167576dfc 100644 --- a/internal/help/EOF.txt +++ b/internal/help/EOF.txt @@ -1,19 +1,24 @@ -The '''EOF''' Function indicates that the end of a file has been reached. - +The [[EOF]] function indicates that the end of a file has been reached. {{PageSyntax}} -:: DO WHILE [[NOT]] EOF(filenumber&) +: {{Parameter|endReached%%}} = EOF([#]{{Parameter|fileNumber&}}) -* Filenumber is the number of the file being read. # is not required. +{{PageDescription}} +* {{Parameter|fileNumber&}} is the number of the file being read. '''#''' is not required. * Returns 0 until the end of a file. This avoids a file read error. -* Returns -1 at the end of the file. -* [[CHR$]](26) can be used to denote the end of a file. +* Returns -1 (true) at the end of the file. +<!-- confusing statement; further details are required: * [[CHR$]](26) can be used to denote the end of a file. --> +* '''Note that [[GET]] can return invalid data at the end of a file.''' Read [[EOF]] after a GET operation to see if the end of the file has been reached and discard last read. -''See also:'' -* [[LOF]] +{{PageSeeAlso}} +* [[OPEN]] +* [[LOF]], [[LEN]] +* [[INPUT (file statement)]] +* [[LINE INPUT (file statement)]] +* [[GET]], [[PUT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/EQV.txt b/internal/help/EQV.txt index 2f6e13871..0b457eed7 100644 --- a/internal/help/EQV.txt +++ b/internal/help/EQV.txt @@ -1,12 +1,12 @@ -The '''EQV''' statement returns a value based on the ''equivalence'' of two conditions or values. +The [[EQV]] operator returns a value based on the ''equivalence'' of two conditions or values. {{PageSyntax}} -:first_value {{KW|EQV}} second_value +: {{Parameter|result}} = {{Parameter|firstValue}} [[EQV]] {{Parameter|secondValue}} -{{PageDescription} -* Returns True only when both values are the same. +{{PageDescription}} +* Returns true (-1) when both values are the same (''equivalent''). * Turns a bit on if both bits are the same, turns a bit off if both bits are different. diff --git a/internal/help/ERASE.txt b/internal/help/ERASE.txt index acf42ffb0..415b40f63 100644 --- a/internal/help/ERASE.txt +++ b/internal/help/ERASE.txt @@ -1,21 +1,19 @@ -The '''ERASE''' statement is used to clear all data from an array. [[$STATIC]] [[Arrays|array]] dimensions will not be changed. - +The [[ERASE]] statement is used to clear all data from an array. [[$STATIC]] [[Arrays|array]] dimensions are not affected. {{PageSyntax}} -:: ERASE ''ArrayName'' [, ''arrayname2''...] +: ERASE ''arrayName'' [, ''arrayName2''...] - -* String array elements will all become null strings("") and numerical array elements will all become 0. +{{PageDescription}} +* All string array elements become null strings ("") and all numerical array elements become 0. * Multiple arrays can be erased using commas between the array names. -* [[$DYNAMIC|Dynamic]] arrays MUST be [[REDIM]]ensioned if they are referenced after erased. -* Dimension subprocedure arrays as [[STATIC]] to use ERASE and not have to REDIM. -* You do not have to include the array brackets in an ERASE call. +* [[$DYNAMIC|Dynamic]] arrays must be [[REDIM]]ensioned if they are referenced after erased. +* Dimension subprocedure arrays as [[STATIC]] to use [[ERASE]] and not have to REDIM. +* You do not have to include array brackets in an [[ERASE]] call. -''See also:'' - +{{PageSeeAlso}} * [[DIM]], [[REDIM]] * [[CLEAR]] * [[STATIC]] diff --git a/internal/help/ERDEV$.txt b/internal/help/ERDEV$.txt index 3aa314ba7..2822b4955 100644 --- a/internal/help/ERDEV$.txt +++ b/internal/help/ERDEV$.txt @@ -1,16 +1,20 @@ -ERDEV$ is a string function that returns the name of the last device to declare an error. +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' + +---- + +[[ERDEV$]] is a string function that returns the name of the last device to declare an error. {{PageSyntax}} -::device$ = ERDEV$ +: {{Parameter|device$}} = [[ERDEV$]] -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * It will contain the 8-byte character device name if the error was declared by a character device (such as a printer), while it will contain the 2-byte block name (A:, B:, etc.) if the device was not a character device. * It is set when [[ERDEV]] is set, meaning that DOS has encountered a error that prevents it from continuing. -''See also:'' +{{PageSeeAlso}} * [[ERDEV]] * [[ERROR]] diff --git a/internal/help/ERDEV.txt b/internal/help/ERDEV.txt index a0cfa0770..19929734b 100644 --- a/internal/help/ERDEV.txt +++ b/internal/help/ERDEV.txt @@ -1,12 +1,18 @@ -ERDEV is an integer function that returns an error code from the last device to create an error. +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' + +---- + +[[ERDEV]] is an integer function that returns an error code from the last device to create an error. -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * The code is bit-encoded containing DOS error information, the first 8-bit (first byte) contain the DOS error code, while the second bit contains device specific information (bits 15, 14, 13, (12-4 always zero), 3, 2, 1 in that order of the device attribute word). -* ERDEV is set by the critical error handler (interrupt 24h) when DOS encounters a error that prevents it from continuing. +* [[ERDEV]] is set by the critical error handler (interrupt 24h) when DOS encounters a error that prevents it from continuing. -''See also:'' [[ERDEV$]], [[ERROR]] + +{{PageSeeAlso}} +[[ERDEV$]], [[ERROR]] diff --git a/internal/help/ERL.txt b/internal/help/ERL.txt index 3108c6682..f94e8ee97 100644 --- a/internal/help/ERL.txt +++ b/internal/help/ERL.txt @@ -1,8 +1,8 @@ -The {{KW|ERL}} function returns the closest previous line number before the last error. +The [[ERL]] function returns the closest previous line number before the last error. {{PageSyntax}} -:''result&'' = {{KW|ERL}} +: ''lastErrorLine&'' = [[ERL]] {{PageDescription}} @@ -11,6 +11,7 @@ The {{KW|ERL}} function returns the closest previous line number before the last * Use [[_ERRORLINE]] to return the actual code line position of an error in a QB64 program. +{{PageExamples}} ''Example:'' Using a fake error code to return the line number position in a program. {{CodeStart}} {{Cl|ON ERROR}} {{Cl|GOTO}} errorfix @@ -35,7 +36,7 @@ errorfix: * [[ERR]] * [[ERROR]] * [[ON ERROR]] -* [[_ERRORLINE]] +* [[_ERRORLINE]], [[_INCLERRORLINE]], [[_INCLERRORFILE$]] * [[ERROR Codes]] diff --git a/internal/help/ERR.txt b/internal/help/ERR.txt index b0df03545..45ed7f8e3 100644 --- a/internal/help/ERR.txt +++ b/internal/help/ERR.txt @@ -1,14 +1,16 @@ -'''ERR''' function returns the last Qbasic error code number. +The [[ERR]] function returns the last QBasic error code number. {{PageSyntax}} -:: errornum% = ERR +: {{Parameter|errorNum%}} = [[ERR]] -* If there is no error it returns 0 -* Can be used in an error handling routine to report the error number. +{{PageDescription}} +* If there is no error, the function returns 0 +* Can be used in an error handling routine to report the last error code number. +{{PageExamples}} ''Example:'' Simulating an error to test a program error handler that looks for a "Subscript out of range" error. {{CodeStart}} '' '' {{Cl|ON ERROR}} {{Cl|GOTO}} handler @@ -31,10 +33,10 @@ handler: {{CodeEnd}} -''See also:'' - +{{PageSeeAlso}} * [[ON ERROR]], [[RESUME]] -* [[ERL]], [[_ERRORLINE]] +* [[ERL]] +* [[_ERRORLINE]], [[_INCLERRORLINE]], [[_INCLERRORFILE$]] * [[ERROR]] * [[ERROR Codes]] diff --git a/internal/help/ERROR.txt b/internal/help/ERROR.txt index d168224e8..9d33eba26 100644 --- a/internal/help/ERROR.txt +++ b/internal/help/ERROR.txt @@ -1,15 +1,17 @@ -The '''ERROR''' statement is used to simulate a program error or to troubleshoot error handling procedures. +The [[ERROR]] statement is used to simulate a program error or to troubleshoot error handling procedures. {{PageSyntax}} -:: ERROR code +: [[ERROR]] {{Parameter|codeNumber%}} +{{PageDescription}} * Can be used to test an error handling routine by simulating an error. * Error code 97 can be used to invoke the error handler for your own use, no real error in the program will trigger error 97. * Use error codes between 100 and 200 for custom program errors that will not be responded to by QB64. +{{PageExamples}} ''Example:'' Creating custom error codes for a program that can be handled by an [[ON ERROR]] handling routine. {{CodeStart}} '' '' {{Cl|ON ERROR}} {{Cl|GOTO}} handler @@ -26,10 +28,10 @@ handler: {{Cl|BEEP}} {{Cl|RESUME}} {{Cl|NEXT}} '' '' {{CodeEnd}} -: '''Note: Don't use error codes under 97 or over 200 as QB64 may respond to those errors and interrupt the program!''' +: '''Note: Don't use error codes under 97 or over 200 as QB64 may respond to those errors and interrupt the program.''' -''See also:'' +{{PageSeeAlso}} *[[ON ERROR]] *[[ERR]], [[ERL]] *[[_ERRORLINE]] diff --git a/internal/help/EXIT.txt b/internal/help/EXIT.txt index ce38e1e04..ba370a207 100644 --- a/internal/help/EXIT.txt +++ b/internal/help/EXIT.txt @@ -1,21 +1,21 @@ -The [[EXIT]] statement is used to exit certain Qbasic procedures. +The [[EXIT]] statement is used to exit certain QBasic procedures. {{PageSyntax}} -::EXIT {DO|WHILE|FOR|SUB|FUNCTION|DEF} +: [[EXIT]] {DO|WHILE|FOR|SUB|FUNCTION} {{PageDescription}} -* EXIT leaves any of the following procedures immediately. -:* [[EXIT]] DO exits a [[DO...LOOP]] when called. -:* [[EXIT]] WHILE exits a [[WHILE...WEND]] loop when called. -:* [[EXIT]] FOR exits a [[FOR...NEXT]] counter loop when called. -:* [[EXIT]] SUB exits a [[SUB]] procedure before it ends. Use before any [[GOSUB]] procedures using [[RETURN]]. -:* [[EXIT]] FUNCTION exits a [[FUNCTION]] procedure before it ends. The value passed by the function's name should be defined. -:* [[EXIT]] DEF exits a [[DEF FN]] function procedure before it ends. The value passed by the function's name should be defined. +* [[EXIT]] leaves any of the following procedures immediately. +** [[EXIT]] DO exits a [[DO...LOOP]]. +** [[EXIT]] WHILE exits a [[WHILE...WEND]] loop. +** [[EXIT]] FOR exits a [[FOR...NEXT]] counter loop. +** [[EXIT]] SUB exits a [[SUB]] procedure before it ends. Use before any [[GOSUB]] procedures using [[RETURN]]. +** [[EXIT]] FUNCTION exits a [[FUNCTION]] procedure before it ends. The value passed by the function's name should be defined. +<!-- ** [[EXIT]] DEF exits a [[DEF FN]] function procedure before it ends. The value passed by the function's name should be defined. --> * EXIT statements normally use an [[IF...THEN]] statement to evaluate a program condition that would require the EXIT. -* To exit a program and allow the last program screen to be displayed with "Press any key to continue", use [[END]]. -* To exit the program immediately you can use [[SYSTEM]]. +* To exit a program and allow the last program screen to be displayed with the message "Press any key to continue...", use [[END]]. +* To exit the program immediately, use [[SYSTEM]]. {{PageSeeAlso}} diff --git a/internal/help/EXP.txt b/internal/help/EXP.txt index 6a825db85..b8f6df041 100644 --- a/internal/help/EXP.txt +++ b/internal/help/EXP.txt @@ -1,20 +1,20 @@ -The '''EXP''' math function returns the value of '''e''' to the power of the parameter used. - +The [[EXP]] math function calculates the exponential function ('''e''' raised to the power of a {{Parameter|numericExpression}}). {{PageSyntax}} -:: value = EXP(exponent) +: {{Parameter|result}} = [[EXP]]({{Parameter|numericExpression}}) -* '''e''' is defined as the base of natural logarithms or as the limit of (1 + 1 / n) ^ n as n goes to infinity -* The exponent value MUST be less than or equal to '''88.02969''' or an [[ERROR Codes|"overflow" error]] will occur! -* Value returned is '''e''' to the exponent parameter. '''e = 2.718282''' (approximately) -* Values returned are [[SINGLE]] by default but will return [[DOUBLE]] precision if the exponent uses a double value. +{{PageDescription}} +* '''e''' is defined as the base of natural logarithms or as the limit of (1 + 1 / n) ^ n, as n goes to infinity. +* The {{Parameter|numericExpression}} must be less than or equal to '''88.02969''' or an [[ERROR Codes|"overflow" error]] will occur. +* Value returned is '''e''' to the exponent parameter ('''e = 2.718282''' approximately). +* Values returned are [[SINGLE]] by default but will return [[DOUBLE]] precision if the {{Parameter|result}} is a variable of type [[DOUBLE]]. * Positive exponent values indicate the number of times to multiply '''e''' by itself. -* Negative exponent values indicate the number of times to divide by '''e'''. Example: e<sup>-3</sup> = 1 / e<sup>3</sup> = 1 /(e * e * e) +* Negative exponent values indicate the number of times to divide by '''e'''. Example: <span style="font-family: Courier New, monospace, Courier; background: #dddddd">e<sup>-3</sup> = 1 / e<sup>3</sup> = 1 / (e * e * e)</span> -''See also:'' +{{PageSeeAlso}} *[[LOG]] *[[Mathematical Operations]] *[http://qb64.net/wiki/index.php?title=Mathematical_Operations#Derived_Mathematical_Functions Derived Trigonometric Functions] diff --git a/internal/help/FIELD.txt b/internal/help/FIELD.txt index 4f92d2748..e71644a69 100644 --- a/internal/help/FIELD.txt +++ b/internal/help/FIELD.txt @@ -1,20 +1,21 @@ -The '''FIELD''' statement creates a [[STRING]] type definition for a [[RANDOM|random]]-access file buffer. +The [[FIELD]] statement creates a [[STRING]] type definition for a [[RANDOM|random]]-access file buffer. {{PageSyntax}} -:{{KW|FIELD}} [#]{{Parameter|fileNumber&}} {{Parameter|fieldWidth1%}} AS {{Parameter|variable1$}}[, {{Parameter|fieldWidthN%}} AS {{Parameter|variableN$}}] +: [[FIELD]] [#]{{Parameter|fileNumber&}} {{Parameter|fieldWidth1%}} AS {{Parameter|variable1$}}[, {{Parameter|fieldWidthN%}} AS {{Parameter|variableN$}}] {{PageDescription}} * {{Parameter|fileNumber%}} is a file number used in the [[OPEN]] statement or a value from the [[FREEFILE]] function. -* Combined size of the {{Parameter|fieldWidth%}} parameters '''MUST not exceed''' the [[LEN]] = recordsize in the [[RANDOM]] [[OPEN]] statement or a [[ERROR Codes|"FIELD overflow" error]] will occur. +* Combined size of the {{Parameter|fieldWidth%}} parameters '''must not exceed the [[LEN]] = recordsize in the [[RANDOM]] [[OPEN]] statement''' or a [[ERROR Codes|"FIELD overflow" error]] will occur. * Variables are limited to [[STRING]] types. Use [[TYPE]] instead of FIELD if you want to use numerical values. -* Once a FIELD is defined in a statement, [[GET]] can read and [[PUT]] can write data without placeholders or variables. +* Once a [[FIELD]] is defined in a statement, [[GET]] can read and [[PUT]] can write data without placeholders or variables. * [[LSET]], [[RSET]], [[PRINT (file statement)|PRINT #]], [[PRINT USING (file statement)|PRINT # USING]], and [[WRITE (file statement)|WRITE #]] can be used to place characters in the file buffer before a [[PUT]]. -* All field definitions for a file are removed when the file is [[CLOSE|closed]] or [[RESET]] and all strings are set to null(""). -* Do NOT re-assign a field defined variable value or use it in an [[INPUT]] statement if you want the variable to remain a field! +* All field definitions for a file are removed when the file is [[CLOSE|closed]] or [[RESET]] and all strings are set to null (""). +* '''Do not re-assign a field defined variable value or use it in an [[INPUT]] statement if you want the variable to remain a field'''. +{{PageExamples}} ''Example:'' Comparing a [[TYPE]] definition with a FIELD [[STRING|string]] definition. Demo using a [[TYPE]] definition to create a file: {{CodeStart}} '' '' {{Cl|TYPE}} ClientType diff --git a/internal/help/FILEATTR.txt b/internal/help/FILEATTR.txt index 04addd8c5..0e2f52d23 100644 --- a/internal/help/FILEATTR.txt +++ b/internal/help/FILEATTR.txt @@ -1,15 +1,19 @@ -The {{KW|FILEATTR}} function can return a file's current file mode or DOS handle. +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' + +---- + +The [[FILEATTR]] function returns a file's current file mode or DOS handle. {{PageSyntax}} -:''result%'' = {{KW|FILEATTR}}({{Parameter|fileNumber%}}, {{Parameter|mode%}}) +: {{Parameter|result%}} = [[FILEATTR]]({{Parameter|fileNumber%}}, {{Parameter|mode%}}) {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * {{Parameter|fileNumber%}} is the number assigned in the file's [[OPEN]] statement. * {{Parameter|mode%}} specifies the type of information to return, which may have the following values -** ''mode%'' = 1: returns the open mode with the following return values: +** {{Parameter|mode%}} = 1: returns the open mode with the following return values: ::{| border="2" cellpadding="1" ! Return || Open Mode |- @@ -23,7 +27,7 @@ The {{KW|FILEATTR}} function can return a file's current file mode or DOS handle |- |  32 ||  [[BINARY]] |} -:* ''mode%'' = 2: returns the [[DOS]] handle number of a file. +** {{Parameter|mode%}} = 2: returns the [[DOS]] handle number of a file. {{PageSeeAlso}} diff --git a/internal/help/FILES.txt b/internal/help/FILES.txt index e6766b09a..23481c62e 100644 --- a/internal/help/FILES.txt +++ b/internal/help/FILES.txt @@ -1,30 +1,34 @@ -The {{KW|FILES}} statement is used to return a list of files in the current directory using a filespec, but long lists will scroll the screen. +The [[FILES]] statement is used to print a list of files in the current directory using a file specification. {{PageSyntax}} -:{{KW|FILES}} [{{Parameter|fileSpec$}}] +: [[FILES]] [{{Parameter|fileSpec$}}] {{PageDescription}} - -* Filespec is a string expression or variable containing a path when required. -* Filespec can use the * and ? wildcard specs like normal DOS DIR statements. -: * denotes one or more wildcard characters in a filename or path spec as any legal file name character(s). -: ? denotes one wildcard letter in a filename or path spec as any legal filename character. -* If {{Parameter|fileSpec$}} is omitted, it is assumed to be <code>"*.*"</code> (all files and folders in the current directory). +* {{Parameter|fileSpec$}} is a string expression or variable containing a path when required. +* {{Parameter|fileSpec$}} can use the * and ? wildcard specifications: +** '''*''' denotes one or more wildcard characters in a filename or path specification as any legal file name character(s). +** '''?''' denotes one wildcard letter in a filename or path specification as any legal filename character. +* If {{Parameter|fileSpec$}} is omitted, it is assumed to be '''"*.*"''' (all files and folders in the current directory). * Illegal filename characters in '''QB64''' include * > < : " | \ / with any amount of dot extensions being allowed in Windows. -* Illegal filename characters in '''Qbasic''' include * ? , > < ; : " | \ / + [ ] and more than one dot extension in [http://www.computerhope.com/issues/ch000209.htm DOS]. -* FILES lists can make the screen roll. Try using SHELL "DIR" with the /P option. [http://www.computerhope.com/dirhlp.htm DIR command]. +* FILES lists can make the screen roll up. Try using SHELL "DIR" with the /P option. [http://www.computerhope.com/dirhlp.htm DIR command]. +==QBasic/QuickBASIC== +* Illegal filename characters in QBasic included '''* ? , > < ; : " | \ / + [ ]''' and more than one dot extension in [http://www.computerhope.com/issues/ch000209.htm DOS]. + +{{PageExamples}} ''Example 1:'' Finding a list of all BAS files in the current folder. {{CodeStart}}{{Cl|FILES}} "*.BAS" {{CodeEnd}} -<center>'''[http://i301.photobucket.com/albums/nn53/burger2227/FILESss.jpg Screenshot shows only the end of a long list of files]'''</center> +<!-- broken link: <center>'''[http://i301.photobucket.com/albums/nn53/burger2227/FILESss.jpg Screenshot shows only the end of a long list of files]'''</center> --> -''Example 2:'' A function that verifies that a file exists if it is NOT empty. Note: Function WILL deleted empty files! +<!-- function obsoleted by _FILEEXISTS; function doesn't use the FILES statement and is not relevant in this context; may be moved to an exclusive page if desired; + +{{Parameter|Example 2:'' A function that verifies that a file exists if it is not empty. Note: This function will delete empty files. {{CodeStart}} '' '' {{Cl|INPUT}} "Enter a file name: ", file$ {{Cl|IF}} Exist%(file$) {{Cl|THEN}} {{Cl|OPEN}} file$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #1: found% = -1 'function call demo @@ -38,10 +42,11 @@ f% = {{Cl|FREEFILE}} {{Cl|IF}} {{Cl|LOF}}(f%) {{Cl|THEN}} Exist% = -1 {{Cl|ELSE}} Exist% = 0: {{Cl|CLOSE}} #f%: {{Cl|KILL}} filename$ 'delete empty files {{Cl|CLOSE}} #f% {{Cl|END FUNCTION}} '' '' -{{CodeEnd}}{{small|Code by Ted Weissgerber}} +{{CodeEnd}}{{small|Code by Ted Weissgerber}}}} +--> - -''Example 3:'' The DIR$ function used in PDS(7.1) returns a filename or a list when more than one exist. The file spec can use a path and/or wildcards. +==Alternative file list solutions== +''Alternative 1:'' The DIR$ function adapted from PDS (7.1) returns a filename or a list when more than one exist. The file spec can use a path and/or wildcards. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} 2 {{Cl|PRINT}} @@ -85,21 +90,16 @@ DIR$ = DirList$(Index%) {{Cl|END FUNCTION}} '' '' {{CodeEnd}} {{small|Code by Ted Weissgerber}} -:''Explanation:'' The function will verify that a file exists (even if it is empty) by returning it's name or it returns an empty string if no file exists. It can return a list of file names by using an empty string parameter("") after sending a wildcard spec to get the first file name. The number of file names found is returned by using the SHARED variable, '''DIRCount%'''. Unlike the PDS DIR$ function, '''it MUST use an empty string parameter until QB64 supports optional parameters!''' The function does NOT delete empty files. +:''Explanation:'' The function will verify that a file exists (even if it is empty) by returning its name, or it returns an empty string if no file exists. It can return a list of file names by using an empty string parameter("") after sending a wildcard spec to get the first file name. The number of file names found is returned by using the SHARED variable, '''DIRCount%'''. Unlike the PDS DIR$ function, '''it must use an empty string parameter as QB64 doesn't support optional parameters.''' The function does not delete empty files. -<center>'''Alternative File List Solution'''</center> -A member created a [[FILELIST$ (function)]] that uses the mouse and does not affect your program screens. It can verify that a file name exists or display a list of long and short file names to choose from. It also avoids program errors when a file name does not exist. +''Alternative 2:'' +* The member-contributed [[FILELIST$]] function uses the mouse and does not affect your program screens. It can verify that a file name exists or display a list of long and short file names to choose from. It also avoids program errors when a file name does not exist. <!-- broken link: [http://i301.photobucket.com/albums/nn53/burger2227/FILE-ss2.jpg FILELIST$ function screenshot] --> -<center>NEW expanded code is available here: [[FILELIST$]]</center> - -<center>[http://i301.photobucket.com/albums/nn53/burger2227/FILE-ss2.jpg FILELIST$ function Screenshot]</center> - - -''See Library:'' File Exist C++ Function that does not create a temp file. [http://qb64.net/wiki/index.php?title=C_Libraries#File_Exist FileExist Function] +<!-- The referenced library is not present in this link anymore ''See Library:'' File Exist C++ Function that does not create a temp file. [http://qb64.net/wiki/index.php?title=C_Libraries#File_Exist FileExist Function] --> {{PageSeeAlso}} -* [[SHELL]], [[SCREEN (function)]] {{text|(See Example 2)}} +* [[SHELL]], [[SCREEN (function)]] {{text|(See Example 3)}} * [[CHDIR]], [[MKDIR]] * [[RMDIR]], [[KILL]] * [[_CWD$]], [[_STARTDIR$]] @@ -107,9 +107,7 @@ A member created a [[FILELIST$ (function)]] that uses the mouse and does not aff * [[DOS]], [[Batch Files]], [[DOS#DIR|DIR]] * [[Windows_Libraries#File_Exist|Windows File Exist Library]] * [[Windows_Libraries#File_Open_and_Save_Dialog|Windows Open and Save Dialog Boxes]] -* [[C_Libraries#Console_Window|C Console Library]] -* [[FILELIST$]], [[DIR$]] {{text|(member file list array functions)}} - +* [[$CONSOLE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/FIX.txt b/internal/help/FIX.txt index d055560c5..e5a70da5e 100644 --- a/internal/help/FIX.txt +++ b/internal/help/FIX.txt @@ -1,21 +1,21 @@ -The '''FIX''' function rounds a numerical value to the next whole number closest to zero. - +The [[FIX]] function rounds a numerical value to the next whole number closest to zero. {{PageSyntax}} -:: result = '''FIX('''''expression''''')''' +: {{Parameter|result}} = [[FIX]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[Data types|type]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} -* [[FIX]] effectively truncates (removes) the fractional part of ''expression'', returning the integer part. -* This means that [[FIX]] rounds down for positive values and up for negative values. +* [[FIX]] effectively truncates (removes) the fractional part of {{Parameter|expression}}, returning the integer part. +** This means that [[FIX]] rounds down for positive values and up for negative values. * Use [[INT]] to round down negative values. Positive values are rounded down by both. +{{PageExamples}} ''Example 1:'' Showing the behavior of [[FIX]] with positive and negative decimal point values. {{CodeStart}} '' '' PRINT FIX(2.5) @@ -48,7 +48,8 @@ The '''FIX''' function rounds a numerical value to the next whole number closest {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} +* [[_CEIL]] * [[INT]], [[CINT]] * [[CLNG]], [[_ROUND]] * [[MOD]], [[\|Integer Division]] diff --git a/internal/help/FOR...NEXT.txt b/internal/help/FOR...NEXT.txt index 0770568be..b03e34ebd 100644 --- a/internal/help/FOR...NEXT.txt +++ b/internal/help/FOR...NEXT.txt @@ -1,37 +1,36 @@ -The '''FOR''' statement creates a counter loop using specified start and stop numerical boundaries. The default increment is + 1. - +The [[FOR]] statement creates a counter loop using specified start and stop numerical boundaries. The default increment is + 1. {{PageSyntax}} -:: '''FOR ''counter_variable'' = ''start_value'' [[TO]] ''stop_value''''' [{{KW|STEP}} ''increment''] -:: . -:: . -:: . -:: '''NEXT''' [''counter_variable''] +: [[FOR]] {{Parameter|counterVariable}} = {{Parameter|startValue}} [[TO]] {{Parameter|stopValue}} [{{KW|STEP}} {{Parameter|increment}}] +:: ''{code}'' +:: ⋮ +: [[NEXT]] [{{Parameter|counterVariable}}] {{Parameters}} -* The FOR ''counter_variable'' name is required to define the counter span and may also be used after the NEXT keyword. -* The ''start_value'' [[TO]] ''stop_value'' can be any literal or variable numerical type. BOTH values are required! -* [[STEP]] can be used for a loop ''increment'' other than the default plus 1 and can be any positive or negative literal or variable numerical value as long as the STEP value corresponds to the loop's ''start value'' and ''stop value''s. -* [[NEXT]] ends the FOR loop code block and increments the counter to the next value even when it exceeds the stop limit. +* The [[FOR]] {{Parameter|counterVariable}} name is required to define the counter span and may also be used after the NEXT keyword. +* The {{Parameter|startValue}} [[TO]] {{Parameter|stopValue}} can be any literal or variable numerical type. Both values are required. +* [[STEP]] can be used for a loop {{Parameter|increment}} other than the default ''plus 1 and can be any positive or negative literal or variable numerical value as long as the STEP value corresponds to the loop's {{Parameter|startValue}} and {{Parameter|stopValue}}. +* [[NEXT]] ends the [[FOR]] loop code block and increments the counter to the next value even when it exceeds the stop limit. -''Usage:'' -* FOR NEXT counter loops must be within the proper start, stop and increment values or the entire loop code block will not be executed. -* Avoid changing the FOR ''counter_variable'''s value inside of the loop. This obfuscates code and is a poor programming practice! -* Once the loop has been started, changing the ''start_value'', ''stop_value'' or ''increment'' value will not affect loop execution. -* '''If the [[STEP]] ''increment'' value does not match the ''start_value'' [[TO]] ''stop_value'' the FOR loop block will be ignored!''' -:* If ''start_value'' is less than ''stop_value'', use default increment or positive [[STEP]] value or the loop will NOT be executed. -:* If ''start_value'' is more than ''stop_value'', use a negative [[STEP]] interval or the loop will NOT be executed. -:* The [[STEP]] ''increment'' value cannot be changed inside of the loop! +{{PageDescription}} +* [[FOR...NEXT]] counter loops must be within the proper start, stop and increment values or the entire loop code block will not be executed. +* Avoid changing the FOR {{Parameter|counterVariable}}'s value inside of the loop. This obfuscates code and is a poor programming practice. +* Once the loop has been started, changing the variables holding the {{Parameter|startValue}}, {{Parameter|stopValue}} or {{Parameter|increment}} value will not affect loop execution. +* '''If the [[STEP]] ''increment'' value does not match the {{Parameter|startValue}} [[TO]] {{Parameter|stopValue}} the FOR loop block will be ignored.''' +** If {{Parameter|startValue}} is less than {{Parameter|stopValue}}, use the default increment or positive [[STEP]] value or the loop will not be executed. +** If {{Parameter|startValue}} is more than {{Parameter|stopValue}}, use a negative [[STEP]] interval or the loop will not be executed. +** The [[STEP]] {{Parameter|increment}} value cannot be changed inside of the loop. * Use '''[[EXIT]] FOR''' to leave a FOR loop early when a certain condition is met inside of the loop. * The [[NEXT]] counter variable name is not required. NEXT loop increments can be separated by colons in nested FOR loops. -* '''NOTE: The counter value AFTER a FOR loop will be incremented one more than the ''stop_value'' requested by the loop!''' -* '''Beware of FOR loop counts that EXCEED the count variable's type limits and may repeat without error in QB64!''' - +* '''NOTE: When the FOR loop is exited after the {{Parameter|stopValue}} is reached, the {{Parameter|counterVariable}}'s value will be {{Parameter|stopValue}} + 1 (or {{Parameter|stopValue}} + {{Parameter|increment}}) +* '''Beware of FOR loop counts that exceed the {{Parameter|counterVariable}} type limits and may repeat without error in QB64.''' +** For example, if {{Parameter|counterVariable}} is of type [[INTEGER]] and the stop limit exceeds 32767, the {{Parameter|counterVariable}} will reset back to -32768 and loop endlessly. +{{PageExamples}} ''Example 1:'' Adding all of the even numbers from 10 to 0. {{CodeStart}} '' '' FOR i = 10 TO 0 {{Cl|STEP}} -2 @@ -59,12 +58,13 @@ PRINT "After loop, i ="; i '' '' bye {{OutputEnd}} +<!-- removed redundant example as Example 2 above shows exactly the same technique ''See Example:'' -* [http://qb64.net/wiki/index.php?title=Controller_Devices#Example Example that shows how ignoring bad FOR loops can work to a program's advantage without errors.] +* [http://qb64.net/wiki/index.php?title=Controller_Devices#Example Example that shows how ignoring bad FOR loops can work to a program's advantage without errors.] --> -''See also:'' -* [[NEXT]], [[STEP]] +{{PageSeeAlso}} +* [[STEP]] * [[DO...LOOP]], [[WHILE...WEND]] diff --git a/internal/help/FOR_(file_statement).txt b/internal/help/FOR_(file_statement).txt index 197290f0a..bb5a5f750 100644 --- a/internal/help/FOR_(file_statement).txt +++ b/internal/help/FOR_(file_statement).txt @@ -1,13 +1,14 @@ -{{KW|FOR (file statement)|FOR}} is used in a {{KW|OPEN}} statement to select the filemode to open the file with. +#REDIRECT [[OPEN#File_Access_Modes]] + +[[FOR (file statement)|FOR]] is used in a [[OPEN]] statement to indicate the file mode with which to open a file. {{PageSyntax}} -:{{KW|OPEN}} ... {{KW|FOR (file statement)|FOR}} {APPEND|BINARY|INPUT|OUTPUT|RANDOM} +: [[OPEN]] ... [[FOR (file statement)|FOR]] {APPEND|BINARY|INPUT|OUTPUT|RANDOM} {{PageDescription}} - -* If {{KW|FOR (file statement)|FOR}} isn't used in a {{KW|OPEN}} statement then the default filemode {{KW|RANDOM}} is used. +* If [[FOR (file statement)|FOR]] isn't used in an [[OPEN]] statement, the default file mode {{KW|RANDOM}} is used. ** {{KW|APPEND}} - Keeps the information of the file intact while you can insert information at the end of it, writing permission only. ** {{KW|BINARY}} - Opens the file in binary mode, use this with binary files. ** {{KW|INPUT (file mode)|INPUT}} - Opens the file for viewing only. @@ -16,7 +17,7 @@ {{PageExamples}} -'''Warning:''' ''Make sure you don't have a file named test.tst before you run this! It will be overwritten if so!'' +'''Warning:''' Make sure you don't have a file named test.tst before you run this or it will be overwritten. {{CodeStart}} @@ -50,13 +51,8 @@ It was overwritten with this and deleted. {{OutputEnd}} - - - {{PageSeeAlso}} -* {{KW|OPEN}} - - +* [[OPEN]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/FRE.txt b/internal/help/FRE.txt index b17bc5f6f..1cbf9f0d7 100644 --- a/internal/help/FRE.txt +++ b/internal/help/FRE.txt @@ -1,30 +1,32 @@ -The '''FRE''' function returns the amount of Memory available in bytes to running programs. - +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' +---- +The [[FRE]] function returns the amount of memory available in bytes to running programs. {{PageSyntax}} -:: memory = FRE(string_expression$) -:: memory = FRE(numerical_expression) +: {{Parameter|memory}} = [[FRE]]({{Parameter|stringExpression$}}) +: {{Parameter|memory}} = [[FRE]]({{Parameter|numericalExpression}}) -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' -* Any string expression returns the size, in bytes, of free string storage space. -* Also compacts the free string storage to a single block of memory. -* 0 returns the same value as using a string expression above. -* -1 returns the size of the largest non-string array in bytes that could be dimensioned. -* -2 returns the amount of stack space, in bytes, available to a running program. -* Any other numerical value returns the size of the next block of string memory storage space. +{{PageDescription}} +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' +* Any {{Parameter|stringExpression$}} returns the size, in bytes, of free string storage space. +** Also compacts the free string storage to a single block of memory. +* {{Parameter|numericalExpression}} can be: +** 0: returns the same value as using a string expression above. +** -1: returns the size of the largest non-string array in bytes that could be dimensioned. +** -2: returns the amount of stack space, in bytes, available to a running program. +** Any other numerical value returns the size of the next block of string memory storage space. -''Example:'' +{{PageExamples}} {{CodeStart}} '' '' ' {{Cl|$DYNAMIC}} PRINT "Sizes in bytes before dimensioning arrays: "; {{Cl|FRE}}(""), {{Cl|FRE}}(0), {{Cl|FRE}}(-1), {{Cl|FRE}}(-2) {{Cl|DIM}} Array(100, 100), Text$(5000) PRINT "Sizes in bytes after dimensioning arrays: "; {{Cl|FRE}}(""), {{Cl|FRE}}(0), {{Cl|FRE}}(-1), {{Cl|FRE}} (-2) '' '' {{CodeEnd}} - -''Notes:'' Sizes returned may vary by computer used. FRE(-2) must be used in a running program! +''Notes:'' Sizes returned may vary by computer used. FRE(-2) must be used in a running program. {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/FREEFILE.txt b/internal/help/FREEFILE.txt index f3b5776ed..c1cff4745 100644 --- a/internal/help/FREEFILE.txt +++ b/internal/help/FREEFILE.txt @@ -1,19 +1,20 @@ -The '''FREEFILE''' function returns an [[INTEGER]] value that is an unused file access number. +The [[FREEFILE]] function returns a [[LONG]] value that is an unused file access number. {{PageSyntax}} -:: file1% = FREEFILE +: fileHandle& = [[FREEFILE]] -* FREEFILE values should be given to unique variables so that each file has a specific variable value assigned to it. +{{PageDescription}} +* [[FREEFILE]] values should be given to unique variables so that each file has a specific variable value assigned to it. * Once the number is assigned in an [[OPEN]] statement, the file number can later be used to read, write or [[CLOSE]] that file. -* Files numbers [[CLOSE]]d are made available to FREEFILE for reuse immediately. -* FREEFILE returns are normally sequential starting with 1. Only file numbers in use will not be returned. -* [[OPEN]] each file number after each FREEFILE return or the values returned may be the same! -* [[OPEN COM]] statements cannot use any number assigned to files already OPEN! +* File numbers [[CLOSE]]d are made available to [[FREEFILE]] for reuse immediately. +* [[FREEFILE]] returns are normally sequential starting with 1. Only file numbers in use will not be returned. +* [[OPEN]] each file number after each [[FREEFILE]] return or the values returned may be the same. +<!-- redundant * [[OPEN COM]] statements cannot use any number assigned to files already OPEN. --> -''See also:'' +{{PageSeeAlso}} * [[GET]], [[PUT]], [[CLOSE]] diff --git a/internal/help/FUNCTION.txt b/internal/help/FUNCTION.txt index 9cd902340..764f6ece6 100644 --- a/internal/help/FUNCTION.txt +++ b/internal/help/FUNCTION.txt @@ -1,49 +1,49 @@ -A '''FUNCTION''' block statement is used when creating a function procedure to return a calculated value to a program. +A [[FUNCTION]] block statement is used to create a function procedure to return a calculated value to a program. {{PageSyntax}} -:: '''FUNCTION procedure_name'''[type-suffix] [(''parameters'')] -:: ... -:: ... 'variable definitions and procedure statements -:: ... -:: '''END FUNCTION''' +: '''FUNCTION procedureName'''[type-suffix] [(''parameters'')] +:: ''{code}'' +:: 'variable definitions and procedure statements +:: ⋮ +:: procedureName = returnValue +: '''END FUNCTION''' -* The function type can be any variable type that it will return to the program and is represented by the type suffix. -* '''QB64 currently cannot use FUNCTION name [[AS]] type!''' This VB functionality is promised in the future. -* Functions hold ONE return value in the function's name which is a variable type. Other values can be passed through ''parameter(s)''. -* Functions are often referred to in program calculations, not called like SUB procedures. [[CALL]] cannot be used with functions! +{{PageDescription}} +* The function type can be any variable type that it will return to the program and is represented by the type suffix. +* Functions hold one return value in the function's name which is a variable type. Other values can be passed through ''parameters''. +* Functions are often referred to in program calculations, not called like SUB procedures. [[CALL]] cannot be used with functions. * If there are no parameters passed or they are [[SHARED]] the ''parameters'' and parenthesis are not required. -* The [[IDE]] may '''require''' that an '''intermediate variable''' be used when calculations define the function's value more than once! In those cases, make the Function's name equal to the intermediate variable's value at the end of the Function. * Variable names within the procedure do not have to match the names used in the reference parameters, just the value types. * All [[$DYNAMIC|dynamic]] variable values return to 0 or null strings when the procedure is exited except when a variable or the entire function is [[STATIC]]. This can save program memory as all [[$DYNAMIC|dynamic]] memory used in a FUNCTION is released on procedure exit. * FUNCTION procedure code can use [[GOSUB]] and [[GOTO]] line numbers or labels inside of the procedure when necessary. * For early function exits use [[EXIT]] [[FUNCTION]] before [[END FUNCTION]] and [[GOSUB]] procedures using [[RETURN]]. -* '''QB64 ignores all procedural [[DECLARE]] statements!''' Define all ''parameter'' [[TYPE]]s in the FUNCTION procedure. +* '''QB64 ignores all procedural [[DECLARE]] statements.''' Define all ''parameter'' [[Data types|types]] in the FUNCTION procedure. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' -* '''Recursive Functions will require a parameter to repeat internal references currently in QB64.''' +* The [[IDE]] can create the FUNCTION and END FUNCTION lines for you. Use the ''New FUNCTION...'' option in the Edit Menu. A box will come up for you to enter a name for the FUNCTION. Enter all code between the FUNCTION and [[END FUNCTION]] lines. -<center>'''Qbasic'''</center> -* Once a FUNCTION is created and used, the Qbasic IDE will [[DECLARE]] it when the file is saved. QB64 doesn't need them! -* The [[IDE]] can create the FUNCTION and END FUNCTION lines for you. Use the Make FUNCTION option in the Edit Menu. A box will come up for you to enter a name for the FUNCTION. Enter all code between the FUNCTION and [[END FUNCTION]] lines. -* Qbasic's IDE may place a [[DEFINT]], [[DEFSNG]], [[DEFLNG]], [[DEFDBL]] or [[DEFSTR]] statement before the FUNCTION line if it is used in the main module. It may even be the wrong variable type needed. It can be changed or removed when necessary. -* Qbasic allowed programmers to add DATA fields anywhere because the [[IDE]] separated the main code from other procedures. +==QBasic/QuickBASIC== +* Once a FUNCTION was created and used, the QBasic IDE would [[DECLARE]] it when the file was saved. '''QB64 doesn't need these declarations.''' +* QBasic's IDE could place a [[DEFINT]], [[DEFSNG]], [[DEFLNG]], [[DEFDBL]] or [[DEFSTR]] statement before the FUNCTION line if it is used in the main module. It may even be the wrong variable type needed. +* QBasic allowed programmers to add DATA fields anywhere because the IDE separated the main code from other procedures. +{{PageExamples}} ''Example 1:'' A simple function that returns the current path. Place [[FUNCTION]] or [[SUB]] procedures after the program [[END]]. {{CodeStart}} '' '' {{Cl|PRINT}} "Current path = "; PATH$ {{Cl|END}} {{Cl|FUNCTION}} PATH$ -f% = {{Cl|FREEFILE}} -file$ = "D0Spath.inf" 'file name uses a zero to prevent an overwrite of existing file name -{{Cl|SHELL}} {{Cl|_HIDE}} "CD > " + file$ 'send screen information to a created text file -{{Cl|OPEN}} file$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #f% 'file should exist with one line of text -{{Cl|LINE INPUT (file statement)|LINE INPUT}} #f%, PATH$ 'read file path text to function name -{{Cl|CLOSE}} #f% -{{Cl|KILL}} file$ + f% = {{Cl|FREEFILE}} + file$ = "D0Spath.inf" 'file name uses a zero to prevent an overwrite of existing file name + {{Cl|SHELL}} {{Cl|_HIDE}} "CD > " + file$ 'send screen information to a created text file + {{Cl|OPEN}} file$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #f% 'file should exist with one line of text + {{Cl|LINE INPUT (file statement)|LINE INPUT}} #f%, PATH$ 'read file path text to function name + {{Cl|CLOSE}} #f% + {{Cl|KILL}} file$ {{Cl|END FUNCTION}} '' '' {{CodeEnd}} @@ -59,21 +59,21 @@ IntegerArray& = ImageBufferSize&(wide&, deep&, mode%) \ 2 ' retu {{Cl|DEFINT}} A-Z {{Cl|FUNCTION}} ImageBufferSize& (Wide&, Deep&, ScreenMode%) -{{Cl|SELECT CASE}} ScreenMode% - {{Cl|CASE}} 1: BPPlane = 2: Planes = 1 - {{Cl|CASE}} 2, 3, 4, 11: BPPlane = 1: Planes = 1 - {{Cl|CASE}} 7, 8, 9, 12: BPPlane = 1: Planes = 4 - {{Cl|CASE}} 10: BPPlane = 1: Planes = 2 - {{Cl|CASE}} 13: BPPlane = 8: Planes = 1 - {{Cl|CASE ELSE}}: BPPlane = 0 -{{Cl|END SELECT}} -ImageBufferSize& = 4 + {{Cl|INT}}((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) 'return the value to function name. + {{Cl|SELECT CASE}} ScreenMode% + {{Cl|CASE}} 1: BPPlane = 2: Planes = 1 + {{Cl|CASE}} 2, 3, 4, 11: BPPlane = 1: Planes = 1 + {{Cl|CASE}} 7, 8, 9, 12: BPPlane = 1: Planes = 4 + {{Cl|CASE}} 10: BPPlane = 1: Planes = 2 + {{Cl|CASE}} 13: BPPlane = 8: Planes = 1 + {{Cl|CASE ELSE}}: BPPlane = 0 + {{Cl|END SELECT}} + ImageBufferSize& = 4 + {{Cl|INT}}((Wide& * BPPlane + 7) / 8) * (Deep& * Planes) 'return the value to function name. {{Cl|END FUNCTION}} '' '' {{CodeEnd}} :''Explanation:'' Function calculates the array byte size required when you [[GET (graphics statement)|GET]] an area of a graphics [[SCREEN]]. Each mode may require a different sized array. Since graphics uses [[INTEGER]] arrays, 2 byte elements, the size returned is divided by 2 in the IntegerArray& calculation function reference. Function returns only 4 for [[SCREEN]] 0 which is a text only mode. -''See also:'' +{{PageSeeAlso}} * [[SUB]], [[SCREEN (statement)]] * [[DEF FN]] * [[EXIT]] (statement), [[END]] diff --git a/internal/help/GET.txt b/internal/help/GET.txt index 3cec4ce81..5c4774a54 100644 --- a/internal/help/GET.txt +++ b/internal/help/GET.txt @@ -1,20 +1,19 @@ -The '''GET #''' file or port device statement reads data by bytes or record positions. - +The [[GET #]] statement reads data from a file or port device by bytes or record positions. {{PageSyntax}} -:: '''GET #''filenumber&'',''' [''position''][, {''holdingvariable''|''holdingarray()''}] +: [[GET #]]{{Parameter|fileNumber&}}, [{{Parameter|position}}][, {{{Parameter|targetVariable}}|{{Parameter|targetArray()}}}] - -* File/port number is the file number used in the [[OPEN]] AS [[BINARY]] or [[RANDOM]] statement. -* The [[INTEGER]] or [[LONG]] byte ''position'' in a [[BINARY]] file or the record ''position'' in a [[RANDOM]] file '''must be greater than zero'''. -* The ''position'' can be omitted if the GETs are consecutive based on the ''holding variable'' [[TYPE]] byte size. -* The ''holding variable'' [[TYPE]] or [[FIELD]] ''variable'' size determines the byte size and the next ''position'' in the file. -* The first file position is 1. This may require adding one to an offset value when documentation uses that position as 0. -* GET does NOT require a byte or record ''position'' or ''holding variable''(or comma) when using a [[FIELD]] statement! -* '''QB64''' can [[PUT]] the entire contents of an array to a file and later GET those contents to a ''holding array''(include brackets). -* '''GET can ignore an [[EOF]] statement and return bad data! [[EOF]] after a GET denotes that the data has ended!''' +{{PageDescription}} +* {{Parameter|fileNumber&}} is the file or port number used in the [[OPEN]] AS [[BINARY]] or [[RANDOM]] statement. +* The [[INTEGER]] or [[LONG]] byte {{Parameter|position}} in a [[BINARY]] file or the record {{Parameter|position}} in a [[RANDOM]] file '''must be greater than zero'''. +* The {{Parameter|position}} can be omitted if the GET operations are consecutive based on the {{Parameter|targetVariable}} [[TYPE]] byte size. +* The {{Parameter|targetVariable}} [[Data types|type]] or [[FIELD]] ''variable'' size determines the byte size and the next {{Parameter|position}} in the file. +* The first byte position in a file is 1. <!-- giving the previous information is enough: This may require adding one to an offset value when documentation uses that position as 0. --> +* GET does not require a byte or record {{Parameter|position}} or {{Parameter|targetVariable}} (or comma) when using a [[FIELD]] statement. +* '''QB64''' can [[PUT]] the entire contents of an array to a file and later GET those contents to a {{Parameter|targetArray()}} (include brackets). +* '''GET may ignore the end of a file and return bad data. If the [[EOF]] function returns -1 after a GET operation, it indicates that the data has ended.''' {{TextStart}} DO UNTIL {{Cb|EOF}}(1) {{Cb|GET}} #1, , value% IF {{Cb|NOT}}({{Cb|EOF}}(1)) THEN {{Cb|PUT}} #2, , value% @@ -22,6 +21,7 @@ The '''GET #''' file or port device statement reads data by bytes or record posi {{TextEnd}} +{{PageExamples}} ''Example 1:'' Opening a RANDOM file using LEN to calculate and LEN = to designate the file record size. {{CodeStart}} '' '' {{Cl|TYPE}} variabletype @@ -98,7 +98,7 @@ showme 'display array after transfer from file : ''Note:'' Use empty brackets in QB64 when using [[GET]] to create an array or [[PUT]] to create a [[BINARY]] data file. -''See also:'' +{{PageSeeAlso}} * [[PUT|PUT #]], [[SEEK]], [[SEEK (statement)]] * [[INPUT (file statement)|INPUT #]], [[GET (TCP/IP statement)]] * [[FIELD]], [[RANDOM]], [[BINARY]] diff --git a/internal/help/GET_(TCP%2FIP_statement).txt b/internal/help/GET_(TCP%2FIP_statement).txt index 1329a2875..a637a1883 100644 --- a/internal/help/GET_(TCP%2FIP_statement).txt +++ b/internal/help/GET_(TCP%2FIP_statement).txt @@ -1,30 +1,31 @@ -GET (in regard to TCP/IP) reads unformatted(raw) data from an open connection, opened with [[_OPENCLIENT]], [[_OPENHOST]] or [[_OPENCONNECTION]] '''QB64''' functions. +'''GET''' reads unformatted (raw) data from an open TCP/IP connection opened with [[_OPENCLIENT]], [[_OPENHOST]] or [[_OPENCONNECTION]]. {{PageSyntax}} -::::::::''Syntax 1:'' GET #handle, ,b$ - -*Reads any available data into variable length string b$ (b$'s length is adjusted to the number of bytes read, so checking EOF is completely unnecessary) using the handle return value from the function used. +''Syntax 1:'' +: '''GET''' ''#handle'', , ''b$'' +* Reads any available data into variable length string b$ (b$'s length is adjusted to the number of bytes read, so checking EOF is unnecessary) using the handle return value from [[_OPENCLIENT]], [[_OPENHOST]] or [[_OPENCONNECTION]]. -::::::::''Syntax 2:'' GET #handle, ,x% - -*Reads an integer, if 2 bytes are available, they are read into x%, if not then nothing is read and EOF(handle) will return -1 (and x%'s value will be undefined) using the handle return value from the function used. +''Syntax 2:'' +: '''GET''' ''#handle'', ,''x%'' +* Reads an integer. If 2 bytes are available, they are read into x%, if not then nothing is read and [[EOF]](handle) will return -1 (and ''x%'''s value will be undefined) using the handle return value from [[_OPENCLIENT]], [[_OPENHOST]] or [[_OPENCONNECTION]]. -:::::'''Communicating using unformatted/raw streamed data:''' -* Benefit: Communicate with any TCP/IP compatible protocol (eg. FTP, HTTP, web-pages, etc) -* Disadvantage: Streamed data has no 'message length' as such, just a continuous bunch of bytes all in a row. Some messages get fragmented and parts of messages can (and often do) arrive at different times. -* The position parameter(between the commas) is not used in TCP/IP statements. -:::::'''Your program MUST cater for these situations manually.''' +==Communicating using unformatted/raw streamed data== +* Benefit: Communicate with any TCP/IP compatible protocol (eg. FTP, HTTP, web-pages, etc). +* Disadvantage: Streamed data has no 'message length', as such just the program deals with a continuous number of bytes in a row. Some messages get fragmented and parts of messages can (and often do) arrive at different times, due to the very nature of the TCP/IP protocol. +* The position parameter (between the commas) is not used in TCP/IP connections. +* The programmer must cater for these situations manually. +{{PageExamples}} ''Example:'' {{CodeStart}} - {{Cl|PUT|PUT #}}c, , a$ ' sends data - {{Cl|GET|GET #}}o, , b$ ' reads any available data into variable length string b$ - {{Cl|GET|GET #}}o, , x% ' if 2 bytes are available, they are read into x% + {{Cl|PUT|PUT #}}​c, , a$ ' sends data + {{Cl|GET|GET #}}​o, , b$ ' reads any available data into variable length string b$ + {{Cl|GET|GET #}}​o, , x% ' if 2 bytes are available, they are read into x% {{CodeEnd}} ''Explanation:'' @@ -34,11 +35,12 @@ GET (in regard to TCP/IP) reads unformatted(raw) data from an open connection, o -''See the examples in [[_OPENCLIENT]] or [[Email Demo]].'' +===More examples=== +* ''See the examples in [[_OPENCLIENT]] or [[Email Demo]].'' -''See also:'' +{{PageSeeAlso}} * [[PUT (TCP/IP statement)]], [[INPUT (TCP/IP statement)]] * [[_OPENCLIENT]], [[_OPENHOST]] * [[_OPENCONNECTION]], [[GET|GET #]] diff --git a/internal/help/GET_(graphics_statement).txt b/internal/help/GET_(graphics_statement).txt index dc8252efd..c699cd20d 100644 --- a/internal/help/GET_(graphics_statement).txt +++ b/internal/help/GET_(graphics_statement).txt @@ -1,33 +1,40 @@ -The {{KW|GET (graphics statement)|GET}} statement is used in graphics to store a box area image of the screen into an {{KW|INTEGER}} array. +The [[GET (graphics statement)|GET]] statement is used in graphics to store a box area image of the screen into an [[INTEGER]] array. + +==Legacy support== +* '''QB64 can manipulate parts of an image using [[_PUTIMAGE]]. For that reason, GET isn't recommended practice anymore and is supported to maintain compatibility with legacy code.''' {{PageSyntax}} -::: '''GET''' [STEP] '''(''column1'', ''row1'')-'''[STEP]'''(''column2'', ''row2''),''' ''Array''([''index''])[, ''offscreen_color''] +: [[GET]] [STEP] ({{Parameter|column1}}, {{Parameter|row1}})-[STEP]({{Parameter|column2}}, {{Parameter|row2}}), {{Parameter|array}}([{{Parameter|index}}])[, {{Parameter|offscreenColor}}] -''[[Parameters]]:'' -* ''Column'' and ''row'' [[INTEGER]] coordinates for the box area must be on the screen except when using an ''offscreen color''. -* [[INTEGER]] Array sizes must be large enough (use width * height of the box area + 4) to hold the data or an error will occur! -* The [[arrays|array]] ''index'' offset is optional. If the offset is zero the brackets may be empty (Qbasic does not require the brackets). -* The ''off screen color'' pixels will be returned as the designated color when part of an image is off screen in QB64 only. +{{Parameters}} +* ''column'' and ''row'' [[INTEGER]] coordinates for the box area must be on the screen except when using an ''offscreenColor''. +* [[INTEGER]] array sizes must be large enough (use width * height of the box area + 4) to hold the data or an error will occur. +* The [[arrays|array]] ''index'' offset is optional. If the offset is zero the brackets may be empty. +* The {{Parameter|offscreenColor}} pixels will be returned as the designated color when part of an image is off screen. -''Usage:'' +{{PageDescription}} * The [[STEP]] keyword can be used to for coordinates relative to the last graphic coordinates used. -* A graphic screen mode MUST be used! See the [[SCREEN]] statement for graphic screen dimensions. -* '''QB64''' GET statements can use coordinates off of the screen when an ''off screen color'' is designated. [[STEP]] can be used for relative coordinates. -* The GET box coordinates are set just like a {{KW|LINE}} box statement is placed. You can use a box to find the correct GET area. +* A graphic screen mode must be used. See the [[SCREEN]] statement for graphic screen dimensions. +* '''QB64''' GET statements can use coordinates off of the screen when an '{{Parameter|offscreenColor}} is designated. [[STEP]] can be used for relative coordinates. +* The GET box coordinates are set just like a [[LINE]] box statement is placed. You can use a box to find the correct GET area. * Once GET has placed the pixel image data in the array, PUT the image or BSAVE it to a file. -* Once the image is stored in an array {{KW|PUT (graphics statement)|PUT}} can be used to place the image on the screen. -* SCREEN 12 can only GET 1/3 of a full SCREEN 12 image (QB64 can save entire screen). Rows would increment 160 each GET. +* Once the image is stored in an array [[PUT (graphics statement)|PUT]] can be used to place the image on the screen. * A [[_SOURCE]] [[handle]] can be set to GET image areas other than the ones on the current screen. Use [[_DEST]] to [[PUT (graphics statement)|PUT]] images there. * To GET more than one image to the same array, designate an offset index that is not being used and is large enough to hold the data. -* The [[INTEGER]] array size can be calculated as slightly larger than the box area width times the height. A closer estimate can be done by reading the array indices from [[UBOUND]] to [[LBOUND]] after a [[GET (graphics statement)|GET]] of a white box area. In QB64 a [[LONG]] array can be used for large or full screen images. -* RGB color settings can be embedded at the beginning of the array for transferring custom colors. ''Index'' the GET image data after the settings. -* In QB64 [[_PUTIMAGE]] is recommended over PUT as it can also do the [[GET (graphics statement)|GET]] directly from the image source without requiring an array. -* [[PUT]] and [[GET]] file statements can also write and read image array data using [[BINARY]] files instead of using [[BSAVE]] or [[BLOAD]]. +* The [[INTEGER]] array size can be calculated as slightly larger than the box area width times the height. A closer estimate can be done by reading the array indices from [[UBOUND]] to [[LBOUND]] after a [[GET (graphics statement)|GET]] of a white box area. In QB64, a [[LONG]] array can be used for large or full screen images. +* RGB color settings can be embedded at the beginning of the array for transferring custom colors. Specify an ''index'' for GET image data to be stored after any extra information added to the beginning of the array. +* '''In QB64, [[_PUTIMAGE]] is recommended over PUT as it can also do the [[GET (graphics statement)|GET]] operation directly from the image source without requiring an array.''' +* '''[[PUT]] and [[GET]] file statements can also write and read image array data using [[BINARY]] files instead of using [[BSAVE]] or [[BLOAD]].''' +==QBasic/QuickBASIC== +* SCREEN 12 could only GET 1/3 of a full SCREEN 12 image. Rows would increment 160 each GET. '''QB64''' can save entire screen at once. + + +{{PageExamples}} ''Example 1:'' How to use GET and PUT to move a sprite with the arrow keys. {{CodeStart}} '' '' {{Cl|DEFINT}} A-Z diff --git a/internal/help/GOSUB.txt b/internal/help/GOSUB.txt index 6f45d9112..84b533724 100644 --- a/internal/help/GOSUB.txt +++ b/internal/help/GOSUB.txt @@ -1,21 +1,21 @@ -'''GOSUB''' sends the program to a sub program that uses a line number or label. - +[[GOSUB]] sends the program flow to a sub procedure identified by a line number or label. {{PageSyntax}} -:: GOSUB label +: GOSUB {{{Parameter|lineNumber}}|{{Parameter|label}}} +{{PageDescription}} +* Use [[RETURN]] in a sub procedure to return to the next line of code after the original [[GOSUB]] call. [[END]] or [[SYSTEM]] can also be used to end program. +<!-- needs clarification: * A procedure loop may be used to return automatically instead of using return. --> +* GOSUB and GOTO can be used '''within''' [[SUB]] or [[FUNCTION]] procedures, but cannot refer to a label located outside the procedure. -* Label is any [[line number]] or line label designated with a colon after it. Don't use the colon in the call. -* [[RETURN]] at the end of the procedure returns to the next code after the original call. [[END]] or [[SYSTEM]] can also be used to end program. -* A procedure loop may be used to return automatically instead of using return. -* GOSUB and GOTO can be used '''within''' [[SUB]] or [[FUNCTION]] procedures, but cannot refer to a label not in the procedure itself. -* '''Note:''' Too many GOSUBs without a [[RETURN]] can eventually cause "Out of Stack Errors" in Qbasic as each GOSUB uses memory to store the location to return to. Each [[RETURN]] frees the memory of the GOSUB it returns to. + +==QBasic/QuickBASIC== +* Too many GOSUBs without a [[RETURN]] can eventually cause "Out of Stack Errors" in QBasic as each GOSUB uses memory to store the location to return to. Each [[RETURN]] frees the memory of the GOSUB it returns to. {{PageExamples}} - ''Example:'' Simple usage of GOSUB {{CodeStart}} {{Cl|PRINT}} "1. It goes to the subroutine." @@ -66,14 +66,12 @@ It returned to IF a = 1 ''Explanation:'' When a = 1 it uses GOSUB to go to "here:", then it uses GOTO to go back to "start:". a is increased by one so when a = 2 it uses GOSUB to go to "there:", and uses RETURN to go the last GOSUB (which is on the IF a = 2 line), it then encounters another RETURN which makes it return to the first GOSUB call we used on the IF a = 1 line. - - -''See also:'' +{{PageSeeAlso}} * [[ON...GOSUB]] * [[ON...GOTO]], [[GOTO]] -* [[ON ERROR]], [[RESUME]] {{text|{Error handlers only)}} +* [[ON ERROR]], [[RESUME]] * [[ON TIMER (n)]] -* [[Line number]] {{text|(removal program)}} +* [[Line number]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/GOTO.txt b/internal/help/GOTO.txt index 49678cc0b..0c01522a9 100644 --- a/internal/help/GOTO.txt +++ b/internal/help/GOTO.txt @@ -1,22 +1,22 @@ -The '''GOTO''' statement sends the procedure to a line label or a line number in the program. - +The [[GOTO]] statement sends the procedure to a line label or a line number in the program. {{PageSyntax}} -::GOTO {line_number|line_label} +: [[GOTO]] {''lineNumber''|''lineLabel''} -''IF GOTO {{PageSyntax}} -:: IF x > 0 [[GOTO]] {line_number|line_label} +'''''IF''' Syntax:'' +: IF condition [[GOTO]] {''lineNumber''|''lineLabel''} -* Codeline is a ''[[line number|linenumber]]'' or ''linelabel'' in a procedure. Keep line numbers and labels inside of the main or sub-procedure body! -* The line label or number MUST already exist or an [[IDE]] status error will be displayed until it is created! +{{PageDescription}} +* ''lineNumber'' or ''lineLabel'' must already exist or an [[IDE]] status error will be displayed until it is created. * Can be used in [[SUB]] or [[FUNCTION]] procedures using their own line labels or numbers. -* The frequent use of GOTO statements can become confusing when trying to follow the code. Could also cause endless loops! -* GOTO is an easy trap for new programmers. Use loops instead when possible. +* The frequent use of GOTO statements can become confusing when trying to follow the code and it could also cause endless loops. +* [[GOTO]] is an easy trap for new programmers. Use loops instead when possible. +{{PageExamples}} ''Example:'' {{CodeStart}} '' '' 1 {{Cl|PRINT}} "first line": {{Cl|GOTO}} gohere @@ -37,13 +37,12 @@ second line :''Explanation:'' After it prints "first line" it goes to the line label "gohere" where it prints "third line", then it goes to the line that is numbered "2" and prints "second line" and goes to line number 3 and an [[END]] statement which ends the program. -''See also:'' +{{PageSeeAlso}} * [[GOSUB]], [[ON ERROR]] * [[ON...GOTO]], [[ON...GOSUB]] * [[DO...LOOP]], [[FOR...NEXT]] * [[IF...THEN]], [[SELECT CASE]] -* [[line number]] /label -* [[Line number|Line number removal program]] +* [[Line number|Line numbers and labels]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/HEX$.txt b/internal/help/HEX$.txt index 8831b5d67..5dc9f9394 100644 --- a/internal/help/HEX$.txt +++ b/internal/help/HEX$.txt @@ -1,19 +1,19 @@ -The {{KW|HEX$}} function returns the base 16 hexadecimal representation of an [[INTEGER]], [[LONG]] or [[_INTEGER64]] value as a [[STRING]]. +The [[HEX$]] function returns the base 16 hexadecimal representation of an [[INTEGER]], [[LONG]] or [[_INTEGER64]] value as a [[STRING]]. {{PageSyntax}} -:''result$'' = {{KW|HEX$}}({{Parameter|decimal_number%}}) +:{{Parameter|result$}} = [[HEX$]]({{Parameter|decimalNumber}}) {{PageDescription}} -* The function returns the string hexadecimal (base-16) representation of a ''decimal'' integer. -* If the parameter is not an Integer, it will be converted to one by HEX$. +* The function returns the string hexadecimal (base-16) representation of {{Parameter|decimalNumber}}. * The function does not return a leading sign space so [[LTRIM$]] is not necessary. -* Can be used in place of [[STR$]] to trim both sides of positive decimal values 0 to 9 only. -* [[VAL]] can convert the string value back to a decimal value by prefixing the string return with "&H", like; dec = VAL("&H" + hexvar$). +<!-- Confusing hack hidden: * Can be used in place of [[STR$]] to trim both sides of positive decimal values 0 to 9 only.}} --> +* [[VAL]] can convert the string value back to a decimal value by prefixing the string return with "&H": {{InlineCode}}dec = VAL("&H" + hexvar$){{InlineCodeEnd}}. -''Example:'' Comparing decimal, hexadecimal and octal string values 0 to 15. +{{PageExamples}} +''Example 1:'' Comparing decimal, hexadecimal and octal string values 0 to 15. {{CodeStart}} '' '' LOCATE 2, 20: PRINT " Decimal | Hexadecimal | Octal " LOCATE 3, 20: PRINT "-----------+-------------+--------" @@ -46,7 +46,7 @@ NEXT n% '' '' ''Note:'' Decimal [[STR$]] values contain a leading sign space so values require an extra space in the template using the slash format. -''Example:'' Converting hex value to decimal. +''Example 2:'' Converting hex value to decimal. {{CodeStart}} h$ = {{Cl|HEX$}}(255) {{Cl|PRINT}} "Hex: "; h$ @@ -59,7 +59,6 @@ Converting Hex value to Decimal: 255 {{OutputEnd}} - {{PageSeeAlso}} * [[OCT$]], [[STR$]], [[VAL]] * [[&H]] {{text|(hexadecimal)}}, [[&O]] {{text|(octal)}}, [[&B]] {{text|(binary)}} diff --git a/internal/help/IF...THEN.txt b/internal/help/IF...THEN.txt index 870b771c5..9b4f29639 100644 --- a/internal/help/IF...THEN.txt +++ b/internal/help/IF...THEN.txt @@ -1,36 +1,37 @@ -'''IF...THEN''' statements make Boolean True or False program evaluations to automate program decision making. +[[IF...THEN]] statements make boolean (true or false) evaluations to automate program decision making. + +{{PageSyntax}} +===Single-line=== +: [[IF]] {{Parameter|conditionStatement}} [[THEN]] ''{code}'' [[ELSE]] ''{alternativeCode}'' +: [[IF]] {{Parameter|conditionStatement}} [[GOTO]] ''lineLabel'' - -''Line'' {{PageSyntax}} -:: '''IF''' ''condition statement'' '''THEN''' ''action'' [[ELSE]] other_action -:: '''IF''' ''condition statement'' [[GOTO]] ''linelabel'' +===Block=== +: [[IF]] {{Parameter|conditionStatement}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSEIF]] {{Parameter|conditionStatement2}} [[THEN]] +:: ''{code}'' +:: ⋮ +: [[ELSE]] +:: ''{code}'' +:: ⋮ +: [[END IF]] -''Block'' {{PageSyntax}} -:: '''IF''' ''condition statement'' '''[[THEN]]''' -::: ''action'' -:: [[ELSEIF]] ''condition statement'' '''[[THEN]]''' ''action'' -:: [[ELSE]] ''action'' -:: '''END IF''' - - -''GOTO {{PageSyntax}} -:: '''IF''' x > 0 [[GOTO]] {line_number|line_label} - - -* The ''conditional'' evaluation by '''IF''' must be true(-1) or a '''non-zero numerical value''' for the THEN ''action'' statements to be executed. +{{PageDescription}} +* The {{Parameter|conditionStatement}} evaluation by [[IF]] must be true (-1) or a '''non-zero numerical value''' for the [[THEN]] ''{code}'' to be executed. * Multiple conditional evaluations can be made using inclusive [[AND (boolean)|AND]] or alternative [[OR (boolean)|OR]] conditional expressions. * [[THEN]] is not required when [[GOTO]] is used to send program flow to a line number or label. -* IF statements can also have alternative evaluations using [[ELSEIF]] and [[ELSE]] conditions. -* When the '''IF''' statement and/or code to be run is more than code line, an [[END IF]] statement '''MUST''' be used. +* [[IF]] statements can also have alternative evaluations using [[ELSEIF]] and [[ELSE]] conditions. +* When the [[IF]] statement and/or code to be run is more than code line, an [[END IF]] statement must be used. * With multiple code lines to run, end the IF statement with THEN and place all of the code on lines below that line. * Multiple code line block statements require that the [[IF...THEN]], [[ELSEIF]], [[ELSE]] and [[END IF]] be on separate lines. -* '''The IDE may return an error of [[NEXT]] without [[FOR]] or [[LOOP]] without [[DO...LOOP|DO]] when [[END IF]] does not end a statement block!''' -* The '''QB64''' IDE may red line the IF THEN statement line until END IF closes the statement block. -* Use '''[[colon]]s''' to execute multiple statements in a one line IF statement. You cannot use [[AND]] statements after [[THEN]]! -* An '''[[underscore]]''' can be used anywhere after the code on one line to continue it to the next line in '''QB64 ONLY'''. -* '''NOTE:''' [[STRING]] values can only be evaluated in an IF statement if a value is compared to a literal or [[CHR$]] string value. '''QB64 may not compile literal IF string statements or indicate an [[IDE]] coding error!''' Use [[LEN]] or [[ASC]] to compare strings numerically. +* '''The IDE may return an error of ''[[NEXT]] without [[FOR]]'' or ''[[LOOP]] without [[DO...LOOP|DO]]'' when [[END IF]] does not end a statement block.''' +* The '''QB64''' IDE will indicate an error in the IF statement line until END IF closes the statement block. +* Use [[colon]]s to execute multiple statements in a single-line IF statement. +* An '''[[underscore]]''' can be used anywhere after the code on a single-line to continue it to the next line in '''QB64'''. +* '''NOTE:''' [[STRING]] values can only be evaluated in an IF statement if a value is compared to a literal or [[CHR$]] string value. '''QB64 may not compile literal IF string statements or indicate an [[IDE]] coding error.''' Use [[LEN]] or [[ASC]] to compare strings numerically. @@ -57,7 +58,7 @@ <center>* '''Note that Basic returns -1 for True and 0 for False.'''</center> - +{{PageExamples}} ''Example 1:'' In a one line IF statement, only [[REM]] can be used to comment out the action without an [[END IF]] error: {{CodeStart}} '' '' {{Cl|INPUT}} "Enter a number over or under 100: ", x @@ -77,7 +78,7 @@ {{CodeEnd}} -''Example 3:'' True or False evaluation of a numerical value executes only when the value is not 0. '''Cannot evaluate [[STRING]] values!''' +''Example 3:'' True or False evaluation of a numerical value executes only when the value is not 0. '''Cannot evaluate [[STRING]] values.''' {{CodeStart}} '' '' {{Cl|INPUT}} "Enter a number or just hit Enter: ", x {{Cl|IF...THEN|IF}} x {{Cl|THEN}} {{Cl|PRINT}} x '' '' @@ -110,9 +111,9 @@ IF Key$ >= {{Cl|CHR$}}(65) AND Key$ <= {{Cl|CHR$}}(90) THEN PRINT "A : ''Explanation:'' Long [[STRING]] expression values are compared by their cumulative [[ASCII]] code values. -<center>'''Qbasic decimal point value comparison errors'''</center> +<center>'''QBasic decimal point value comparison errors'''</center> * Floating decimal point numerical values may not be compared as exactly the same value. QB64 will compare them the same. -:''Example:'' Qbasic will print ''unequal'' in the IF comparison code below even though it is exactly the same value printed. +:''Example:'' QBasic would print ''unequal'' in the IF comparison code below even though it is exactly the same value printed. {{CodeStart}} '' '' x# = 5 / 10 y# = 6 / 10 @@ -123,12 +124,12 @@ z# = x# + y# : Note: QB64 will make the calculation correctly and print ''equal''. Change older program code that relies on the error accordingly. -''See also:'' +{{PageSeeAlso}} * [[ELSEIF]], [[ELSE]] * [[AND (boolean)]], [[OR (boolean)]] * [[NOT]], [[GOTO]] * [[SELECT CASE]] -* [[Boolean]] {{text|(numerical comparisons return a True or False value)}} +* [[Boolean]] {{text|(numerical comparisons return a true or false value)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/IMP.txt b/internal/help/IMP.txt index 69f96e58e..f7c7248c7 100644 --- a/internal/help/IMP.txt +++ b/internal/help/IMP.txt @@ -1,15 +1,15 @@ -The '''IMP''' logical operator converts the result of two comparative values and returns a bit result. +The [[IMP]] logical operator converts the result of two comparative values and returns a bit result. {{PageSyntax}} -::first_value {{KW|IMP}} second_value +: {{Parameter|result}} = {{Parameter|firstValue}} [[IMP]] {{Parameter|secondValue}} {{PageDescription}} -* Returns a different result than {{KW|AND}}, {{KW|OR}} or {{KW|XOR}} would. -* Evaluates: first_value ''implies'' second_value. -::If first_value is True then second_value must also be True. -::So if first_value is True, and second_value False, then the condition is False, otherwise True (see table) +* Returns a different result from [[AND]], [[OR]] or [[XOR]]. +* Evaluates if {{Parameter|firstValue}} '''''imp'''lies'' {{Parameter|secondValue}}. +**If {{Parameter|firstValue}} is true then {{Parameter|secondValue}} must also be true. +**So if {{Parameter|firstValue}} is true, and {{Parameter|secondValue}} false, then the condition is false, otherwise it is true (see table below). {{Template:LogicalTruthTable}} diff --git a/internal/help/INKEY$.txt b/internal/help/INKEY$.txt index 93df4ca0b..3b4684f1a 100644 --- a/internal/help/INKEY$.txt +++ b/internal/help/INKEY$.txt @@ -1,18 +1,18 @@ -The '''INKEY$''' Function returns user input as [[ASCII]] [[STRING]] character(s) from the keyboard buffer. +The [[INKEY$]] function returns user input as [[ASCII]] [[STRING]] character(s) from the keyboard buffer. {{PageSyntax}} -:: keypress$ = '''INKEY$''' +: {{Parameter|keypress$}} = [[INKEY$]] -''Usage:'' +{{PageDescription}} * Returns [[ASCII]] character string values in upper or lower cases. See: [[UCASE$]] and [[LCASE$]] * Returns "" if no key has been pressed since the last keyboard read. * Some control keys cannot be read by INKEY$ or will return 2 byte [[ASCII]] codes. -* INKEY$ can also clear a [[SLEEP]] keypress or the keyboard buffer in a loop. +* INKEY$ can also be used to clear a [[SLEEP]] key press or the keyboard buffer in a loop. * Assign the INKEY$ return to a string variable to save the key entry. -* [[LOCATE]] ,,1 displays the INKEY$ cursor. Use LOCATE ,,0 to turn it off. -* Use [[_DEST]] [[_CONSOLE]] before INKEY$ statements to be used in a [[$CONSOLE|console]] window. +* <span style="font-family: Courier New, monospace, Courier; background: #dddddd">[[LOCATE]] , , 1</span> displays the INKEY$ cursor. Use <span style="font-family: Courier New, monospace, Courier; background: #dddddd">LOCATE , , 0</span> to turn it off. +* Use [[_DEST]] [[_CONSOLE]] before reading INKEY$ to receive input from a [[$CONSOLE|console]] window. * Returns can be evaluated as certain [[ASCII]] characters or codes. {{WhiteStart}}' '''ASCII Keyboard Codes''' ' @@ -40,7 +40,7 @@ The '''INKEY$''' Function returns user input as [[ASCII]] [[STRING]] character(s ==Two Byte Combinations== * INKEY$ 2 byte combinations always begin with [[CHR$]](0). [[ASC]] will always read the first byte code as zero. -* QB64 can read the second byte code using: '''{{text|code2 <nowiki>=</nowiki> ASC(press$, 2)|green}}''' Qbasic can read it using: '''{{text|code2 <nowiki>=</nowiki> ASC(RIGHT$(press$, 1))|green}}''' +* Read the second byte code using: '''{{text|code2 <nowiki>=</nowiki> ASC(press$, 2)|green}}''' <center>'''[[ASCII#Two_Byte_Codes|Two Byte Ctrl, Alt and Shift + Function key combinations]]'''</center> @@ -86,14 +86,15 @@ The '''INKEY$''' Function returns user input as [[ASCII]] [[STRING]] character(s {{WhiteEnd}} :In '''QB64''', [[CVI]] can be used to get the [[_KEYDOWN]] 2-byte code value. Example: '''{{text|status <nowiki>=</nowiki> _KEYDOWN(CVI(CHR$(0) + "P"))|green}}''' -==Examples== +{{PageExamples}} ''Example 1:'' Clearing the keyboard buffer after [[SLEEP]] delays for later [[INPUT]]. {{CodeStart}}{{Cl|PRINT}} "Press any keyboard typing key to end SLEEP" {{Cl|SLEEP}} {{Cl|DO}}: K$ = {{Cl|INKEY$}}: {{Cl|PRINT}} K$: {{Cl|LOOP}} {{Cl|UNTIL}} K$ = "" '' '' {{CodeEnd}} -:''Explanation:'' [[SLEEP]] key presses will be kept in the keyboard buffer and may be added into an [[INPUT]] later! +:''Explanation:'' [[SLEEP]] key presses will be kept in the keyboard buffer and may be added into an [[INPUT]] later. +:See also: [[_KEYCLEAR]] ''Example 2:'' Entering a Ctrl + letter keypress combination will print [[ASCII]] Control characters 1 to 26. . @@ -191,16 +192,40 @@ DO {{Cl|_PUTIMAGE}} (x, y), image {{Cl|LOOP}} '' '' {{CodeEnd}} {{small|Adapted from code by Daniel}} -: ''Note:'' The image can be placed off of the screen without error! The image moves 10 pixels to move faster. [[CLS]] eliminates any background. +: ''Note:'' The image can be placed off of the screen without error. The image moves 10 pixels to move faster. [[CLS]] eliminates any background. + + +''Example 7:'' Creating upper [[ASCII]] characters in a QB program using '''Alt +''' three number keys: +{{CodeStart}} +DO + A$ = "": {{Cl|WHILE}} A$ = "": A$ = {{Cl|INKEY$}}: {{Cl|WEND}} + {{Cl|IF...THEN|IF}} {{Cl|LEN}}(A$) = 2 {{Cl|THEN}} '2 byte INKEY$ return + B$ = {{Cl|RIGHT$}}(A$, 1) 'read second byte + b% = {{Cl|ASC}}(B$) 'read second byte code + {{Cl|IF...THEN|IF}} b% > 119 {{Cl|AND (boolean)|AND}} b% < 130 {{Cl|THEN}} ' Alt + number codes only + C% = b% - 119 ' convert to actual number + {{Cl|IF...THEN|IF}} C% > 9 {{Cl|THEN}} C% = 0 + num$ = num$ + {{Cl|LTRIM$}}({{Cl|STR$}}(C%)) + {{Cl|END IF}} + {{Cl|END IF}} +{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|LEN}}(num$) = 3 ' 3 digit codes only + +{{Cl|PRINT}} num$ +{{Cl|PRINT}} {{Cl|CHR$}}({{Cl|VAL}}(num$)'' '' +{{CodeEnd}}{{small|Code by Ted Weissgerber}} +{{OutputStart}} 155 ¢ {{OutputEnd}} +:''Explanation:'' Hold down Alt key and press 3 keyboard code number keys. '''Number pad keys may not work.''' Note that [[INKEY$]] cannot read Alt, Ctrl or Shift key presses without a key combination and the return is CHR$(0) + CHR$(code). + ''See also:'' * [[_KEYHIT]], [[_KEYDOWN]], [[_MAPUNICODE]] +* [[_KEYCLEAR]] * [[INPUT]], [[LINE INPUT]] * [[INPUT$]], [[INP]] * [[CHR$]], [[ASCII]] -* [[ASC]], [[Scancodes]](keyboard) +* [[ASC]], [[Scancodes]] (keyboard) * [[Windows_Libraries#Hot_Keys_.28maximize.29|Windows hot keys]] diff --git a/internal/help/INP.txt b/internal/help/INP.txt index 87293dbc6..7db315949 100644 --- a/internal/help/INP.txt +++ b/internal/help/INP.txt @@ -1,16 +1,18 @@ -'''INP''' returns a value from a computer register or port values at a specified physical address. '''QB64 currently has limited access!''' +[[INP]] returns a value from a computer register or port values at a specified physical address. {{PageSyntax}} -:: i = INP(address) +: {{Parameter|i}} = [[INP]]({{Parameter|address}}) -* Address can be a Decimal or Hexadecimal [[INTEGER]] value. -* INP reads directly from a register or port address. +* '''QB64 has limited access to registers. VGA memory and registers are emulated.''' +* Address can be a decimal or hexadecimal [[INTEGER]] value. +* [[INP]] reads directly from a register or port address. * It does not require a [[DEF SEG]] memory segment address like [[PEEK]] or [[POKE]] do. -* Reads color port intensity settings after ''[[OUT]] &H3C7, attribute'' sets the starting attribute read mode. +* Reads color port intensity settings after {{InlineCode}}[[OUT]] &H3C7, attribute{{InlineCodeEnd}} sets the starting attribute read mode. +{{PageExamples}} ''Example 1:'' Reading the current RGB color settings used in a bitmap to an array. {{CodeStart}} '' '' SCREEN 12 @@ -100,9 +102,10 @@ K$ = {{Cl|INKEY$}} ScanKey% = keyflags%(scancode%) {{Cl|END FUNCTION}} '' '' {{CodeEnd}} +: ''Note:'' [[_KEYDOWN]] can be used to read multiple keys simultaneously and is the '''recommended practice'''. -''See also:'' +{{PageSeeAlso}} * [[OUT]] {{text|(write to register)}}, [[PEEK]] {{text|(read memory)}} * [[INKEY$]], [[_KEYHIT]], [[_KEYDOWN]] * [[Bitmaps]], [[Scancodes]] {{text|(keyboard)}} diff --git a/internal/help/INPUT$.txt b/internal/help/INPUT$.txt index 206a8ec69..a32a76a0d 100644 --- a/internal/help/INPUT$.txt +++ b/internal/help/INPUT$.txt @@ -1,26 +1,28 @@ -The '''INPUT$''' function is used for the program input of a certain number of bytes from a user's keyboard input, a file or a port. - +The [[INPUT$]] function is used to receive data from the user's keyboard, an open file or an open port. {{PageSyntax}} -:: INPUT$(bytes%[, file_or_port_number]) +: {{Parameter|result$}} = [[INPUT$]]({{Parameter|numberOfBytes%}}[, fileOrPortNumber]) -* Keyboard input is limited to the [[INTEGER]] number of bytes(characters) designated by program. -* The keyboard is the default device when a file or port number is omitted. The byte number is number of key presses to read. +* Keyboard input is limited to the [[INTEGER]] {{Parameter|numberOfBytes%}} (characters) designated by program. +* The keyboard is the default device when a file or port number is omitted. The {{Parameter|numberOfBytes%}} is number of key presses to read. * INPUT$ will wait until the number of bytes are read from the keyboard or port. One byte per loop is recommended with ports. -* INPUT$ will display a cursor in a fixed spot if [[LOCATE]] , , 1 is used in the cursor parameter previous to a read. -* Bytes cannot exceed 32767 in [[BINARY]] opened files or a Qbasic error will result. -* [[RANDOM]] opened file bytes can be up to the [[LEN]] = record length statement or 128 if no statement is used. -* File or port number is the number that was used in the [[OPEN]] AS statement. -* Returns [[STRING]] values including spaces or non letter\number ASCII characters. -* Backspacing is ignored and will add the [[CHR$]](8) character to an entry! -* Use [[LOCATE]],,1 to view the cursor entry. Turn off the cursor using LOCATE ,,0. -* Ctrl + Break will not stop the Qbasic program until there is a full INPUT$ key entry. -* Use [[_DEST]] [[_CONSOLE]] before INPUT$ statements to be used in a [[$CONSOLE|console]] window. +* [[RANDOM]] opened file bytes can be up to the [[LEN]] = recordLength statement, or 128 if no statement is used. +* fileOrPortNumber is the number that was used in the [[OPEN]] AS statement. +* Returns [[STRING]] values including spaces or even extended [[ASCII]] characters. +* Backspace key results in the [[CHR$]](8) character being added to an entry. +* Use {{InlineCode}}[[LOCATE]] , , 1{{InlineCodeEnd}} to view the cursor entry. Turn the cursor off using {{InlineCode}}LOCATE , , 0{{InlineCodeEnd}}. +* Use [[_DEST]] [[_CONSOLE]] before INPUT$ is used to receive input from a [[$CONSOLE|console]] window. -''Example 1:'' A Keyboard limited length entry can be made with a fixed blinking cursor. Entry must be completed before it can be shown. +==QBasic/QuickBASIC== +* {{Parameter|numberOfBytes%}} could not exceed 32767 in [[BINARY]] files or a QBasic error would occur. +* Ctrl + Break would not interrupt the QBasic program until there was a full INPUT$ key entry. In '''QB64''' Ctrl + Break will immediately exit a running program. + + +{{PageExamples}} +''Example 1:'' A keyboard limited length entry can be made with a fixed blinking cursor. Entry must be completed before it can be shown. {{CodeStart}} '' '' {{Cl|LOCATE}} 10, 10, 1 'display fixed cursor at location year$ = {{Cl|INPUT$}}(4) 'waits until all 4 digits are entered @@ -46,7 +48,7 @@ IF {{Cl|LOF}}(1) <= 32767 THEN Text$ = {{Cl|INPUT$}}(LOF(1), 1) :''Explanation:'' The IF statement gets the entire contents when the file size is less than 32768. The program can then work with the string by using [[MID$]] or [[INSTR]]. Note: A text file string will also have '''CrLf''' line break end characters [[CHR$]](13) + [[CHR$]](10). -''See also:'' +{{PageSeeAlso}} * [[INPUT]], [[LINE INPUT]] {{text|(keyboard input)}} * [[INPUT (file mode)]], [[INPUT (file statement)|INPUT #]], [[LINE INPUT (file statement)|LINE INPUT #]] {{text|(file input)}} * [[OPEN]], [[LOC]] {{text|(file)}} diff --git a/internal/help/INPUT.txt b/internal/help/INPUT.txt index 4a7286622..7cf8e2d90 100644 --- a/internal/help/INPUT.txt +++ b/internal/help/INPUT.txt @@ -1,39 +1,39 @@ -The '''INPUT''' statement requests a [[STRING]] or numerical keyboard entry from a program user. - +The [[INPUT]] statement requests a [[STRING]] or numerical keyboard entry from the user. {{PageSyntax}} -:: '''INPUT''' [;] '''"'''[Question or statement text]'''"{,|;}''' '''''variable'''''[, ...] -:: '''INPUT ; ''variable'''''[, ...] +: [[INPUT]] [;] "[Question or statement text]"{,|;} {{Parameter|variable}}[, ...] +: [[INPUT]] ; {{Parameter|variable}}[, ...] -''[[Parameters]]:'' -* [[semicolon]] after the INPUT keyword keeps the entry on the same row after enter is pressed and prevents screen roll. -* The quoted text or question MUST be a literal [[STRING|string]] created by the programmer if used. '''Quoted text cannot use variables!''' -* [[Quotation mark]]s are required except when a semicolon follows INPUT. A question mark will appear before entry cursor. -* [[semicolon]] immediately after the text statement will display a ? mark with a space after it. Use a [[comma]] for input statements. -* ''variable [[type]]'' determines the allowable numerical value entries in QB64. Text numerical entries limited to D, E, [[&H]], [[&O]] or [[&B]]. +{{Parameters}} +* A [[semicolon]] after the [[INPUT]] keyword keeps the entry on the same row after enter is pressed and prevents the screen contents from rolling up. +* The optional prompt "Question or statement text" must be a literal predefined [[STRING|string]]. '''The prompt cannot use a variable.''' +* [[Quotation mark]]s are required except when a semicolon follows [[INPUT]]. A question mark will appear before the cursor. +* A [[semicolon]] immediately after the text statement will display a question mark with a space after it. Use a [[comma]] for input statements. -''Usage:'' -* '''QB64 will not return Redo from start errors''' as user input is limited to input within the scope of the variable [[type]] used. -:: Text entries can use any entry including numerical. '''QB64 will ignore commas in single variable text entries!''' -:: Numerical entries can use numbers only up to the input variable's numerical [[TYPE]] limit. -:: [[INTEGER]], [[LONG]], and [[_INTEGER64]] entries will ignore decimal points entered and will use all numbers. -* INPUT is capable of returning more than one ''variable'' value by separating input variables with commas in the statement. -::The program user will have to know to separate each entry value with a comma when they use it. -:: [[STRING|String]] and numerical variables can both be used in multiple entry requests separated by commas. -:: '''QB64 will allow comma separated entries to not be entered by the user without error!''' -* '''Use [[LINE INPUT]] for text input entries that may contain commas such as address or name entries!''' -* The user must press enter for the INPUT procedure to end. Multiple entries can be skipped. -* Will accept the [[scientific notation]] letter D or E inside of [[SINGLE]] or [[DOUBLE]] numerical values. -* Numerical entries starting with [[&H]], [[&O]] and [[&B]] can be made also. -* INPUT removes all leading or trailing spaces in a string value entry. '''QB64 does NOT remove those spaces!''' -* The statement stops a program until enter is pressed. Not good in programs using a mouse (see [[INKEY$]] loops). -* Use [[_DEST]] [[_CONSOLE]] before INPUT statements to be used in a [[$CONSOLE|console]] window. +{{PageDescription}} +* '''QB64''' does not return ''Redo from start'' errors like QBasic did, as user input is limited to the scope of the variable [[Data types|type]] used. +* Text entries (with a [[STRING]] variable]] can receive any characters, including numerical. '''QB64 will ignore commas in single variable text entries.''' +* The [[Data types|type]] of the {{Parameter|variable}} used to store user input determines the valid numerical range for value entries in QB64, with non-numerical characters limited to D, E, [[&H]], [[&O]] or [[&B]]. +** For example, if you use an [[INTEGER]] variable, as in {{InlineCode}}INPUT "Initial value: ", myValue%{{InlineCodeEnd}}, the valid range is -32768 to 32767. +** [[INTEGER]], [[LONG]], and [[_INTEGER64]] entries will ignore decimal points entered and will use all numbers. +* INPUT can be used to get more than one {{Parameter|variable}} value from the user. Do so by separating input variables with commas in the code. +** The program must inform the user that more than one variable is requested, in order to enter each value separated with a comma at runtime. +** [[STRING|String]] and numerical variables can both be used in multiple entry requests separated by commas. +** '''QB64''' allows comma separated entries to be skipped by the user without generating an error. +* '''Use [[LINE INPUT]] for text input entries that may contain commas such as address or name entries.''' +* The user must press enter for the INPUT procedure to end. <!-- redundant: Multiple entries can be skipped. --> +* [[INPUT]] accepts the [[scientific notation]] letters D or E in [[SINGLE]] or [[DOUBLE]] numerical values. +* Numerical values starting with [[&H]], [[&O]] and [[&B]] can also be entered. +<!-- not valid for QB64, not worth mentioning then denying: * INPUT removes all leading or trailing spaces in a string value entry. '''QB64 does NOT remove those spaces!''' --> +* The statement halts a program until enter is pressed, which may not be desired in programs using mouse input (see [[INKEY$]] loops). +* Use [[_DEST]] [[_CONSOLE]] before INPUT statements to receive input from a [[$CONSOLE|console]] window. -''Example 1:'' Using a variable in an input text message using PRINT. INPUT text cannot use variables! +{{PageExamples}} +''Example 1:'' Using a variable in an input text message using PRINT. INPUT prompts cannot use variables. {{CodeStart}} '' '' {{Cl|INPUT}} "Enter your name: ", name$ {{Cl|PRINT}} name$ + " please enter your age: ";: {{Cl|INPUT}} "", age% 'empty string with comma @@ -42,7 +42,7 @@ The '''INPUT''' statement requests a [[STRING]] or numerical keyboard entry from :''Explanation:'' Use an empty string with a comma to eliminate the question mark that would appear without the string. -''Example 2:'' How QB64 avoids a ''Redo from start'' multiple entry error. Use commas between values! +''Example 2:'' How QB64 avoids a ''Redo from start'' multiple entry error. Use commas between values. {{CodeStart}} '' '' {{Cl|DO}} '' '' {{Cl|INPUT}} "What is your name, age, and sex(M/F)"; name$, age%, sex$ @@ -75,7 +75,7 @@ n$ = {{Cl|UCASE$}}(name$) ' convert search name to upper case : ''Explanation:'' The {{text|red|red}} [[semicolon]] after INPUT acts like a semicolon after a [[PRINT]], which keeps the print cursor on the same row. -''See also:'' +{{PageSeeAlso}} * [[INPUT$]], [[INKEY$]] * [[LINE INPUT]], [[LOCATE]] * [[INPUT (file statement)|INPUT #]], [[LINE INPUT (file statement)|LINE INPUT #]] {{text|(file input)}} diff --git a/internal/help/INPUT_(TCP%2FIP_statement).txt b/internal/help/INPUT_(TCP%2FIP_statement).txt index 5c900ea1c..619161a8d 100644 --- a/internal/help/INPUT_(TCP%2FIP_statement).txt +++ b/internal/help/INPUT_(TCP%2FIP_statement).txt @@ -1,34 +1,39 @@ -INPUT reads a formatted message from an opened connection using the [[_OPENHOST]], [[_OPENCLIENT]] or [[_OPENCONNECTION]] '''QB64''' function handle returns. +'''INPUT''' reads a formatted message from a TCP/IP connection opened using [[_OPENHOST]], [[_OPENCLIENT]] or [[_OPENCONNECTION]]. {{PageSyntax}} -:: INPUT #connection_handle, data1[, data2, ...etc] +: '''INPUT''' #{{Parameter|connectionHandle}}, data1[, data2, ...etc] -* Use INPUT # to avoid reading fragmented data messages. -* If any part of the INPUT # process doesn't complete, then [[EOF]](handle) will return -1. -* INPUT # can read multiple data in one read. GET # would need a [[TYPE]] variable to read multiple values. +{{PageDescription}} +* Use '''INPUT #''' to avoid reading fragmented data messages. +* If any part of the '''INPUT #''' process doesn't complete, then [[EOF]]({{Parameter|connectionHandle}}) will return -1. +* INPUT # can read multiple data in one read. '''GET #''' would need a [[TYPE]] variable to read multiple values. -::::::'''Communicating using QB64 Formatted messages:''' + +==Availability== +* '''Version 0.954 and older'''. +** For version 1.000 and up use [[GET (TCP/IP statement)]] + + +==Communicating using QB64's formatted messages== * Benefit: QB64 handles sending and receiving data in messages. It knows how long each message is and waits for the full message to arrive, avoiding partial messages which have been fragmented from being returned. * Disadvantage: Really only useful for communicating with other QB64 programs (or other programs aware of QB64's header format). -::::'''See''' [[TCP/IP Message Format]] '''for the QB64 header information''' - - -:'''NOTE:''' In the following examples 'h' denotes the host's handle, 'c' the client's handle and 'o' as other handle. +{{PageExamples}} +'''Note:''' In the following examples 'h' denotes the host's handle, 'c' the client's handle and 'o' as other handle. ''Example 1:'' Host sends 2 messages to client and reads data from others. {{CodeStart}} '' '' {{Cl|PRINT (TCP/IP statement)|PRINT}} #c, a$ ' sends the string value a$ (size is calculated by an INPUT) PRINT #c, x% ' if x was equal to 5, this would send " 5 " (without the quotation marks) -'''INPUT #'''o, a$ ' reads the next available message (if arrived) or sets a$'s length to 0 '' '' + '''INPUT #'''o, a$ ' reads the next available message (if arrived) or sets a$'s length to 0 '' '' {{CodeEnd}} - :''Explanation:'' INPUT #o,x% 'effectively reads the next message, performs the VAL function upon it and stores the result in x%. If any part of this process doesn't work then EOF(o) will return -1. + * INPUT of multiple QB64 formatted messages in the one statement will only succeed if every variable can be filled with valid data from the input buffer, if not, EOF returns -1 (failed), any read data is reverted to the buffer and the values of every variable become undefined. However, multiple INPUT can be very beneficial in the aid of communicating multiple data items in the one message. For example: @@ -47,13 +52,14 @@ INPUT reads a formatted message from an opened connection using the [[_OPENHOST] IF TIMER > t! THEN EXIT DO ' 3 second timeout LOOP WHILE {{Cl|EOF}}(myhost) '' '' {{CodeEnd}} -:''Explanation:'' Note that communications MUST be set up in advance for the host and user to know that more than one piece of data is available! Data timing also may affect those communications. Data could be missed using [[GET (TCP/IP statement)]] or [[PUT (TCP/IP statement)]]s as data lengths are unknown. +:''Explanation:'' Note that communications must be set up in advance for the host and user to know that more than one piece of data is available! Data timing also may affect those communications. Data could be missed using [[GET (TCP/IP statement)]] or [[PUT (TCP/IP statement)]]s as data lengths are unknown. -::::::See the example in [[_OPENCONNECTION]]. +===More examples=== +* See the example in [[_OPENCONNECTION]]. -''See also:'' +{{PageSeeAlso}} * [[PRINT (TCP/IP statement)]], [[GET (TCP/IP statement)]], [[PUT (TCP/IP statement)]] * [[_OPENHOST]], [[_OPENCLIENT]], [[_OPENCONNECTION]], [[INPUT (file statement)]] * [[TCP/IP Message Format]] diff --git a/internal/help/INPUT_(file_mode).txt b/internal/help/INPUT_(file_mode).txt index f93a65e82..47a22de03 100644 --- a/internal/help/INPUT_(file_mode).txt +++ b/internal/help/INPUT_(file_mode).txt @@ -1,25 +1,28 @@ -The '''INPUT''' file mode can only [[OPEN]] existing files with data in them for program [[INPUT (file statement)|INPUT]]. +#REDIRECT [[OPEN#File_Access_Modes]] + +The '''INPUT''' file mode in an [[OPEN]] statement opens an existing file for [[INPUT (file statement)|INPUT]]. {{PageSyntax}} -:: OPEN filename$ FOR INPUT AS #filenumber% +: [[OPEN]] {{Parameter|fileName$}} FOR '''INPUT''' AS #filenumber% -* If the filename does not exist, INPUT will create a program [[ERROR Codes|file error]]! Use [[_FILEEXISTS]] in QB64 to avoid errors. +* If {{Parameter|fileName$}} does not exist, attempting to open it FOR INPUT will create a program [[ERROR Codes|file error]]. Use [[_FILEEXISTS]] to avoid errors. * The file number can be determined automatically by using a [[FREEFILE]] variable value. * Mode can use [[INPUT (file statement)|INPUT]] #, [[LINE INPUT (file statement)|LINE INPUT]] # or [[INPUT$]] to read the file data. -* Use the [[EOF]] function to avoid reading data past the end of a file and creating an [[ERROR Codes|INPUT error]]! -* Input file statements will use the same filenumber as the OPEN statement. +* Use the [[EOF]] function to avoid reading data past the end of a file and creating an [[ERROR Codes|INPUT error]]. +* Input file statements will use the same file number as the OPEN statement. * The INPUT mode allows the same file to be opened in another mode with a different number. -* '''NOTE: [[LINE INPUT (file statement)|LINE INPUT]] will work faster in [[BINARY]] than INPUT mode in QB64 to stay compatible with QB.''' +* '''NOTE: [[LINE INPUT (file statement)|LINE INPUT]] will work faster in [[BINARY]] than INPUT mode in QB64 to stay compatible with QBasic.''' +{{PageExamples}} ''Example:'' Avoiding an INPUT mode or [[INPUT (file statement)|INPUT #]] read error using a FileExist function. QB64 can use the [[_FILEEXISTS]] function. {{CodeStart}} '' '' DIM Fdata$(100) INPUT "Enter data file name: ", datafile$ - IF FileExist%(datafile$) THEN + IF _FILEEXISTS(datafile$) THEN D% = {{Cl|FREEFILE}}: count = 0 {{Cl|OPEN}} datafile$ FOR {{Cl|INPUT (file mode)|INPUT}} AS #D% DO UNTIL {{Cl|EOF}}(D%) @@ -30,21 +33,15 @@ The '''INPUT''' file mode can only [[OPEN]] existing files with data in them for {{Cl|CLOSE}} #D% ELSE : PRINT "File not found!" END IF - - {{Cl|FUNCTION}} FileExist% (filename$) - f% = {{Cl|FREEFILE}} - {{Cl|OPEN}} filename$ FOR {{Cl|APPEND}} AS #f% ' check that file exists - IF {{Cl|LOF}}(f%) THEN FileExist% = -1 {{Cl|ELSE}} {{Cl|CLOSE}} #f%: {{Cl|KILL}} filename$ - {{Cl|CLOSE}} #f% - {{Cl|END FUNCTION}} '' '' {{CodeEnd}} -: ''Explanation:'' The function opens the filename in [[APPEND]] mode to see if there is data in the file. It also creates the file if it did not exist. [[LOF]] will return 0 if the file is empty and cannot be read. In fact you can [[KILL]] the file if it is empty. If it is not empty then the function returns -1 and the existing file can be opened for INPUT and read by the program. [[_FILEEXISTS]] doesn't create any files. +: ''Explanation:'' The [[_FILEEXISTS]] function is used before {{InlineCode}}OPEN datafile$ FOR INPUT AS #D%{{InlineCodeEnd}}, which would generate an error in case the file didn't exist. -''See also:'' +{{PageSeeAlso}} * [[INPUT (file statement)|INPUT #]], [[LINE INPUT (file statement)|LINE INPUT #]], [[INPUT$]] {{text|(file input)}} * [[INPUT]], [[LINE INPUT]], [[INPUT$]] {{text|(keyboard input)}} * [[APPEND]], [[RANDOM]], [[OUTPUT]], [[BINARY]] +* [[READ]], [[DATA]] * [[_FILEEXISTS]], [[_DIREXISTS]] diff --git a/internal/help/INPUT_(file_statement).txt b/internal/help/INPUT_(file_statement).txt index fdcccfb96..b842ee8bd 100644 --- a/internal/help/INPUT_(file_statement).txt +++ b/internal/help/INPUT_(file_statement).txt @@ -1,30 +1,28 @@ -The '''INPUT #''' file or port statement reads sequential data using one variable or a comma separated list of matching variable types. - +The [[INPUT #]] file or port statement reads sequential data using one variable or a comma separated list of matching variable types. {{PageSyntax}} -:: '''INPUT #''filenumber&'', ''variable'''''[, listof!, variables$,...] +: [[INPUT #]]{{Parameter|fileNumber&}}, {{Parameter|variable1}}[, {{Parameter|variable2}}, ..., {{Parameter|variableN}}] {{Parameters}} -* ''filenumber'' is a positive [[LONG]] integer value used to [[OPEN]] the file FOR [[INPUT (file mode)|INPUT]] mode only. -* The [[type]] of the ''variable'' define the value or list of values to be returned from the file. Numeric types must match the values returned. -* As reflected in the syntax you can list a number of variables with different types seperated by a comma and they will hold the values in the file (keep in mind that the information in the file should reflect the variable types used). +* {{Parameter|fileNumber&}} is a positive [[LONG]] integer value used to [[OPEN]] the file FOR [[INPUT (file mode)|INPUT]] mode. +* The [[type]] of the ''variable'' used defines the value or list of values to be returned from the file. Numeric types must match the values returned. +* As reflected in the syntax you can list a number of variables with different types seperated by a comma and they will hold the values in the file (keep in mind that the information in the file should match the variable types used). -''Usage:'' -* The file number can be determined by the programmer or an unused number can be returned by the [[FREEFILE]] function. -* INPUT # reads file data from a filenumber& [[OPEN]]ed in the [[INPUT (file mode)|INPUT]] file mode. -* INPUT # can read one variable at a time from a list or read the entire list by [[comma]] separating a list of input variables. -* Variable types MUST match the numerical [[type]]s being read! [[STRING]] variables can return numeric values not in quotes. +{{PageDescription}} +* The file number can be determined by the programmer or be an unused number returned by the [[FREEFILE]] function. +* Variable types must match the numerical [[type]]s being read. [[STRING]] variables can return unquoted numeric values. * Leading or trailing spaces of [[STRING]] values must be inside of quotes. [[WRITE (file statement)|WRITE #]] writes strings inside of quotes automatically. [[PRINT (file statement)|PRINT #]] removes quotes. -* INPUT # will read each value until it encounters a comma for the next value in a list. +* [[INPUT #]] will read each value until it encounters a comma for the next value in a list. * Use the [[EOF]] function to avoid reading past the end of a file. -* Files created by [[WRITE (file statement)|WRITE #]] usually have the same number of values on each file line. If INPUT reads more or less values, it may read beyond the End of File or return bad data input! -* Use the [[LINE INPUT (file statement)]] for files created by PRINT # or PRINT #, USING. -* '''INPUT can read Excel CSV files, but beware of unquoted text or numerical values containing commas!''' +* Files created by [[WRITE (file statement)|WRITE #]] usually have the same number of values on each file line. If INPUT reads more or less values, it may read beyond the [[EOF|end of file]] or return bad data. +* Use the [[LINE INPUT (file statement)]] for files created with PRINT # or PRINT #, USING. +* '''INPUT can read Excel CSV files, but beware of unquoted text or numerical values containing commas.''' +{{PageExamples}} ''Example 1:'' Writes new data to a text file sequentially and reads it back to the program screen. {{CodeStart}} '' '' filename$ = "testfile.dat" diff --git a/internal/help/INSTR.txt b/internal/help/INSTR.txt index 8daebec20..08c286d7d 100644 --- a/internal/help/INSTR.txt +++ b/internal/help/INSTR.txt @@ -1,20 +1,31 @@ -The '''INSTR''' function searches for the first occurance of a search [[STRING]] within a string and returns the position it was found. +The [[INSTR]] function searches for the first occurence of a search [[STRING]] within a base string and returns the position it was found. {{PageSyntax}} -:: position% = INSTR([start%,] basestring$, searchstring$) +: {{Parameter|position%}} = [[INSTR]]([{{Parameter|start%}},] {{Parameter|baseString$}}, {{Parameter|searchString$}}) -* The basestring position of the first character of the searchstring is returned by the function if found. -* Position returned will be 0 if the search found no matches in the base string. -* Start [[INTEGER]] position is optional. Must be at least 1 (start of a string) when used or an [[ERROR Codes|Illegal function call]] will occur. -* The Start position is useful when making multiple searches in the same string. Otherwise it starts at the beginning again! -* Base string and search string are any literal or variable [[STRING]] values. -* The search string should be smaller than the base string! -* Non-zero position return values can be used as a new start position by adding 1 to re-search the base string. +{{Parameters}} +* The optional literal or variable [[INTEGER]] {{Parameter|start%}} indicates where in the {{Parameter|baseString$}} the search must start. +* The {{Parameter|baseString$}} is a literal or variable [[STRING]] value to be searched for an exact match including [[UCASE$|letter cases]]. +* The {{Parameter|searchString$}} is a literal or variable [[STRING]] value being searched. + + +{{PageDescription}} +* The function returns the {{Parameter|position%}} in the {{Parameter|baseString$}} where the {{Parameter|searchString$}} was found. +* {{Parameter|position%}} will be 0 if the search found no matches in the base string. +* [[INSTR]] returns 0 if an empty {{Parameter|baseString$}} is passed, and returns 1 with an empty {{Parameter|searchString$}}. +* The {{Parameter|start%}} position is useful when making multiple searches in the same string. See the example below. +* The {{Parameter|searchString$}} should be smaller or equal in [[LEN|length]] to the {{Parameter|baseString$}}, or 0 is returned. +* Non-zero {{Parameter|position%}} return values can be used as a new start position by adding 1 to re-search the base string. See the example below. * In a loop, INSTR can search an entire file for occurences of certain words. See the [[MID$ (statement)|MID$]] statement example. +==QBasic/QuickBASIC== +* The {{Parameter|start%}} position had to be at least 1 or greater when used or there will be an [[ERROR Codes|Illegal function call]] error. In '''QB64''', a {{Parameter|start%}} value of 0 or negative is interpreted as 1 and doesn't generate an error. + + +{{PageExamples}} ''Example:'' Reading more than one instance of a word in a string using the INSTR return value as the start value plus 1. {{CodeStart}} '' '' text$ = "The cats and dogs where playing, even though dogs don't like cats." @@ -33,9 +44,11 @@ There is 'cats' in the string at position: 62 : ''Explanation:'' When the INSTR return value is 0 there are no more instances of a string in a string so the search loop is exited. -''See also:'' +{{PageSeeAlso}} * [[MID$]], [[MID$ (statement)]] * [[LEFT$]], [[RIGHT$]] +* [[LCASE$]], [[UCASE$]] +* [[STRING]], [[INTEGER]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/INT.txt b/internal/help/INT.txt index 6595fcc35..ae4228fe3 100644 --- a/internal/help/INT.txt +++ b/internal/help/INT.txt @@ -1,32 +1,33 @@ -The '''INT''' function rounds a numeric value down to the next whole number or [[INTEGER]](toward less negative). +The [[INT]] function rounds a numeric value down to the next whole number. {{PageSyntax}} -:: result = '''INT('''''expression''''')''' +: {{Parameter|result}} = [[INT]]({{Parameter|expression}}) {{Parameters}} -* The ''expression'' is any [[TYPE]] of literal or variable numerical value or mathematical calculation. +* {{Parameter|expression}} is any [[Data types|type]] of literal or variable numerical value or mathematical calculation. {{PageDescription}} -* [[INT]] returns the first whole number [[INTEGER]] that is less than the ''expression'' value. +* [[INT]] returns the first whole number [[INTEGER]] that is less than the {{Parameter|expression}} value. * This means that [[INT]] rounds down for both positive and negative numbers. -* Use [[FIX]] to round negative values up. It is identical to INT with positive values. +* Use [[FIX]] to round negative values up. It is identical to [[INT]] for positive values. +{{PageExamples}} ''Example:'' Displaying the rounding behavior of [[INT]]. {{CodeStart}} PRINT INT(2.5) PRINT INT(-2.5) {{CodeEnd}} {{OutputStart}} -2 + 2 -3 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[CINT]], [[CLNG]], [[FIX]] * [[CSNG]], [[CDBL]] * [[_ROUND]], [[_CEIL]] diff --git a/internal/help/INTEGER.txt b/internal/help/INTEGER.txt index 0afcce2ce..3ce973aac 100644 --- a/internal/help/INTEGER.txt +++ b/internal/help/INTEGER.txt @@ -1,25 +1,26 @@ -'''INTEGER''' is a 2 byte number type definition that can hold whole numerical values. +[[INTEGER]] is a 2-byte number type definition that can hold whole numerical values. {{PageSyntax}} -:: DIM ''variable'' AS INTEGER +: [[DIM]] ''variable'' AS [[INTEGER]] * Integers do not use decimal point values but will round those off to the nearest even whole number. -* Qbasic Integer values can range from -32768 to 32767 without an "overflow" error. -* For larger Integer values Qbasic can use the [[LONG]] Integer values. -* '''QB64''' INTEGER values greater than 32767 may become negative signed values as the top bit designates a negative value. -* '''QB64''' [[_UNSIGNED]] Integers can range from 0 to 65535. +* QBasic integer values can range from -32768 to 32767 without an "overflow" error. +* For larger integer values use the [[LONG]] integer type. +* '''QB64''' [[INTEGER]] values greater than 32767 become negative signed values instead of throwing an "overflow" error, as the top bit designates a negative value. See example 1 below. +* '''QB64''' [[_UNSIGNED]] integers can range from 0 to 65535. * '''QB64''' _UNSIGNED [[_INTEGER64]] values range from 0 to 18446744073709551615 -* Many Graphic programs require INTEGER arrays or DEFINT. +* Many graphic programs require [[INTEGER]] arrays. * Variable type suffix is % or ~% for [[_UNSIGNED]]. Suffix can also be placed after a literal or hexadecimal numerical value. * [[LONG]] integers use the '''&''' suffix and [[_INTEGER64]] use the '''&&''' suffix. * Values can be converted to 2 byte [[ASCII]] string values using [[MKI$]] and back with [[CVI]]. -* '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +* '''When a variable has not been defined or has no type suffix, the value defaults to [[SINGLE]].''' +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''Example 1:'' Qbasic signed integers were limited from -32768 to 32767, but could not exceed 32767 or it would error: +{{PageExamples}} +''Example 1:'' QBasic signed integers were limited from -32768 to 32767, but could not exceed 32767 or it would error: {{CodeStart}} '' '' {{Cl|DO...LOOP|DO}}: {{Cl|_LIMIT}} 2000 i% = i% + 1 @@ -47,7 +48,7 @@ i~% = 70000 :''Explanation:'' In QB64 an unsigned integer value of 65536 would be 0 with values increasing by the value minus 65536. -''See also:'' +{{PageSeeAlso}} * [[DIM]], [[DEFINT]] * [[LONG]], [[_INTEGER64]] * [[LEN]], [[MKI$]], [[CVI]] diff --git a/internal/help/INTERRUPT.txt b/internal/help/INTERRUPT.txt index a28e446e8..183a9f037 100644 --- a/internal/help/INTERRUPT.txt +++ b/internal/help/INTERRUPT.txt @@ -1,21 +1,24 @@ -The '''INTERRUPT''' statement is an assembly routine for accessing computer information registers. +The [[INTERRUPT]] statement is an assembly routine for accessing computer information registers. +==Legacy support== +* Registers are emulated in '''QB64''' to allow older programs to be compiled. To enable mouse input in your programs, the recommended practice is to use [[_MOUSEINPUT]] and related functions. + {{PageSyntax}} -:: '''[[CALL]] INTERRUPT('''''intnum'', ''inregs'', ''outregs''''')''' +: [[CALL]] [[INTERRUPT]]({{Parameter|intNum}}, {{Parameter|inRegs}}, {{Parameter|outRegs}}) - -*Available on QuickBasic versions 4 up, it requires the library to be loaded. Command line: QB.EXE /L in QB4.5 . -* Interrupt number is the interrupt reference vector table address. See: [http://www.ctyme.com/intr/cat.htm Ralf Brown's Interrupt List] -* Inregs are the values placed into the call and outregs are the register return values. -* INTERRUPT can only use ax, bx, cx, dx, bp, si, di, and the flags values. -* '''NOTE: QB64 does not currently support INT 33h mouse functions above 3 or INT requests other than 33''' -* The [[TYPE]] definition below will work for both INTERRUPT and [[INTERRUPTX]] statement calls: +{{Parameters}} +* Registers are emulated in QB64 and there is no support for {{Parameter|intNum}} 33h mouse functions above 3 or {{Parameter|intNum}} requests other than 33. +* {{Parameter|inRegs}} are the values placed into the call and {{Parameter|outRegs}} are the register return values. -''RegType.BI''  '$INCLUDE file can be used by INTERRUPT or INTERRUPTX +==QBasic/QuickBASIC== +* Available in QuickBASIC versions 4 and up and required an external library to be loaded. <!-- Command line: QB.EXE /L in QB4.5 --> '''QB64''' emulates the statement without an external library. +* {{Parameter|intNum}} is the interrupt reference vector table address. For historic reference, see: [http://www.ctyme.com/intr/cat.htm Ralf Brown's Interrupt List] +* The [[TYPE]] definition below will work for both [[INTERRUPT]] and INTERRUPTX statement calls +* INTERRUPT can use all of the below TYPE elements when they are required. {{TextStart}} '' '' {{Cb|TYPE}} RegTypeX ax AS INTEGER @@ -31,18 +34,16 @@ The '''INTERRUPT''' statement is an assembly routine for accessing computer info {{Cb|END TYPE}} '' '' {{TextEnd}} {{CodeStart}} -{{Cl|DIM}} {{Cl|SHARED}} inregs {{Cb|AS}} RegTypeX, outregs {{Cb|AS}} RegTypeX +{{Cl|DIM}} {{Cl|SHARED}} inregs {{Cl|AS}} RegTypeX, outregs {{Cl|AS}} RegTypeX {{CodeEnd}} +: QBasic's ''RegType.BI'' $INCLUDE file can be used by INTERRUPT or [[INTERRUPTX]] - -''See also:'' +{{PageSeeAlso}} * [[$INCLUDE|$INCLUDE:]] * [[QB.BI]], [[CALL ABSOLUTE]] * [[INTERRUPTX]] - - -''Download Ethan Winer's FREE Qbasic Book and Programs:'' [http://www.ethanwiner.com/fullmoon.html WINER.ZIP] +* Ethan Winer's free QBasic Book and Programs: [http://www.ethanwiner.com/fullmoon.html WINER.ZIP] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/INTERRUPTX.txt b/internal/help/INTERRUPTX.txt index f6cf2b7a4..e14be32a6 100644 --- a/internal/help/INTERRUPTX.txt +++ b/internal/help/INTERRUPTX.txt @@ -1,20 +1,24 @@ -The '''INTERRUPTX''' statement is an assembly routine for accessing computer information registers. +The [[INTERRUPTX]] statement is an assembly routine for accessing computer information registers. +==Legacy support== +* Registers are emulated in '''QB64''' to allow older programs to be compiled. To enable mouse input in your programs, the recommended practice is to use [[_MOUSEINPUT]] and related functions. + {{PageSyntax}} -:: '''[[CALL]] INTERRUPTX('''intnum, inregs, outregs''')''' +: [[CALL]] [[INTERRUPTX]]({{Parameter|intNum}}, {{Parameter|inRegs}}, {{Parameter|outRegs}}) -*Available on QuickBasic versions 4 up, it requires the library to be loaded. Command line: QB.EXE /L in QB4.5 . -* Interrupt number is the interrupt reference vector table address. See: [http://www.ctyme.com/intr/cat.htm Ralf Brown's Interrupt List] -* Inregs are the values placed into the call and outregs are the register return values. -* INTERRUPTX can use all of the TYPE values when they are required. -* '''NOTE: QB64 does not currently support INT 33h mouse functions above 3 or INT requests other than 33''' -* The [[TYPE]] definition below will work for both [[INTERRUPT]] and INTERRUPTX statement calls: +{{Parameters}} +* Registers are emulated in QB64 and there is no support for {{Parameter|intNum}} 33h mouse functions above 3 or {{Parameter|intNum}} requests other than 33. +* {{Parameter|inRegs}} are the values placed into the call and {{Parameter|outRegs}} are the register return values. -''RegType.BI''  '$INCLUDE file can be used by INTERRUPT or INTERRUPTX +==QBasic/QuickBASIC== +* Available in QuickBASIC versions 4 and up and required an external library to be loaded. <!-- Command line: QB.EXE /L in QB4.5 --> '''QB64''' emulates the statement without an external library. +* {{Parameter|intNum}} is the interrupt reference vector table address. For historic reference, see: [http://www.ctyme.com/intr/cat.htm Ralf Brown's Interrupt List] +* The [[TYPE]] definition below will work for both [[INTERRUPT]] and INTERRUPTX statement calls +* INTERRUPT can use all of the below TYPE elements when they are required. {{TextStart}} '' '' {{Cb|TYPE}} RegTypeX ax AS INTEGER @@ -27,23 +31,19 @@ The '''INTERRUPTX''' statement is an assembly routine for accessing computer inf flags AS INTEGER ds AS INTEGER es AS INTEGER -{{Cb|END TYPE}} +{{Cb|END TYPE}} '' '' {{TextEnd}} -{{CodeStart}} '' '' -{{Cl|REM}} {{Cl|$INCLUDE}}: 'RegType.BI' 'Use only with the RegType or {{Cl|QB.BI}} files - -{{Cl|DIM}} {{Cl|SHARED}} inregs {{Cl|AS}} RegTypeX, outregs AS RegTypeX +{{CodeStart}} +{{Cl|DIM}} {{Cl|SHARED}} inregs {{Cl|AS}} RegTypeX, outregs {{Cl|AS}} RegTypeX {{CodeEnd}} +: QBasic's ''RegType.BI'' $INCLUDE file can be used by INTERRUPT or [[INTERRUPTX]] - -''See also:'' -* [[$INCLUDE|$INCLUDE:]] -* [[QB.BI]], [[CALL ABSOLUTE]] +{{PageSeeAlso}} +* [[$INCLUDE|$INCLUDE:]] +* [[QB.BI]], [[CALL ABSOLUTE]] * [[INTERRUPT]] - - -''Download Ethan Winer's FREE Qbasic Book and Programs:'' [http://www.ethanwiner.com/fullmoon.html WINER.ZIP] +* Ethan Winer's free QBasic Book and Programs: [http://www.ethanwiner.com/fullmoon.html WINER.ZIP] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/IOCTL$.txt b/internal/help/IOCTL$.txt index 4c3a75629..6ee7a51da 100644 --- a/internal/help/IOCTL$.txt +++ b/internal/help/IOCTL$.txt @@ -1,19 +1,21 @@ -The {{KW|IOCTL$}} function receives messages from an open device, format of the messages received is device dependent (see manual of the device to see if it is {{KW|IOCTL}} compatible). Most devices are '''NOT''' {{KW|IOCTL}} compatible. +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' +---- + +The [[IOCTL$]] function receives messages from an open device, format of the messages received is device dependent (see manual of the device to see if it is [[IOCTL]] compatible). Most devices are '''not''' [[IOCTL]] compatible. {{PageSyntax}} -:''result$'' = {{KW|IOCTL$}}([#]{{Parameter|fileNumber%}}) +:{{Parameter|result$}} = [[IOCTL$]]([#]{{Parameter|fileNumber%}}) {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' -* {{Parameter|fileNumber%}} is the file number for the {{KW|OPEN}}ed device and {{Parameter|result$}} is the message received from the device. +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' +* {{Parameter|fileNumber%}} is the file number for the [[OPEN]]ed device and {{Parameter|result$}} is the message received from the device. *'''Note:''' The device must first be opened with the [[OPEN]] statement. {{PageSeeAlso}} -* {{KW|IOCTL}} -* {{KW|OPEN}} - +* [[IOCTL]] +* [[OPEN]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/IOCTL.txt b/internal/help/IOCTL.txt index 2df6cbc71..13e70dc36 100644 --- a/internal/help/IOCTL.txt +++ b/internal/help/IOCTL.txt @@ -1,23 +1,26 @@ -The {{KW|IOCTL}} statement sends a message to an open IOCTL compatible device. +'''This page is maintained for historic purposes. The keyword is [[Keywords currently not supported by QB64|not supported in QB64]].''' +---- + +The [[IOCTL]] statement sends a message to an open IOCTL compatible device. {{PageSyntax}} -:{{KW|IOCTL}} [#]{{Parameter|fileNumber%}}, {{Parameter|message$}} +:[[IOCTL]] [#]{{Parameter|fileNumber%}}, {{Parameter|message$}} {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * {{Parameter|fileNumber%}} is the number of an open device * {{Parameter|message$}} is the message you want to send. * The device must first be opened with the {{KW|OPEN}} statement. -* Use {{KW|IOCTL$}} to receive messages from the device. -* The message sent is device-specific (read manual to see if it is {{KW|IOCTL}} compatible). -* {{KW|IOCTL}} doesn't work with most devices, it doesn't work with BASIC devices (LPTn:, COMn:, SCRN:, CONS:) or DOS block devices (A: to Z:). +* Use [[IOCTL]] to receive messages from the device. +* The message sent is device-specific (read manual to see if it is [[IOCTL]] compatible). +* [[IOCTL]] doesn't work with most devices, it doesn't work with BASIC devices (LPTn:, COMn:, SCRN:, CONS:) or DOS block devices (A: to Z:). {{PageSeeAlso}} -* {{KW|IOCTL$}} -* {{KW|OPEN}} +* [[IOCTL$]] +* [[OPEN]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/KEY(n).txt b/internal/help/KEY(n).txt index 0d1eed613..0d5ccba7c 100644 --- a/internal/help/KEY(n).txt +++ b/internal/help/KEY(n).txt @@ -1,11 +1,11 @@ '''KEY(n)''' assigns, enables, disables or suspends event trapping of a keypress by setting the flag [[ON]], [[STOP]] or [[OFF]]. - {{PageSyntax}} -:: KEY(''number'') {[[ON]] | [[OFF]] | [[STOP]]} +: KEY({{Parameter|number}}) {[[ON]] | [[OFF]] | [[STOP]]} +{{PageDescription}} * Predefined and user defined KEY event number assignments to use with KEY(n): {{WhiteStart}} '''1 to 10'''.............Reserved '''F1 to F10''' function keys only. '''11, 12, 13 and 14'''...Reserved '''Up, Left, Right and Down''' numeric keypad arrows only @@ -15,11 +15,12 @@ * Keypresses can be read during [[INKEY$]], [[INPUT$]] or [[INPUT]] procedures without losing the input. * Key event reads will also interrupt [[SLEEP]]. * [[KEY(n)]] specific status modes are: -::*'''ON''' enables specific keypress events to be monitored. -::*'''STOP''' suspends specific keypress reads, but remembers them. When re-enabled the key presses will be returned. -::*'''OFF''' disables specified keypress reads and will not remember the event. +**'''ON''' enables specific keypress events to be monitored. +**'''STOP''' suspends specific keypress reads, but remembers them. When re-enabled the key presses will be returned. +**'''OFF''' disables specified keypress reads and will not remember the event. +{{PageExamples}} ''Example 1:'' How to trap the LEFT direction keys on both the dedicated cursor keypad and the numeric keypad. {{CodeStart}} '' '' {{Cl|KEY n|KEY}} 15, {{Cl|CHR$}}(128) + {{Cl|CHR$}}(75) ' Assign trap for LEFT arrow key on the cursor keypad @@ -59,7 +60,7 @@ SLEEP '' '' {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[ON KEY(n)]], [[KEY n]] {{text|(softkeys)}} * [[_KEYHIT]], [[_KEYDOWN]] * [[Keyboard scancodes]] diff --git a/internal/help/KEY_LIST.txt b/internal/help/KEY_LIST.txt index 546fa5eff..8e33742b5 100644 --- a/internal/help/KEY_LIST.txt +++ b/internal/help/KEY_LIST.txt @@ -1,23 +1,17 @@ -The '''KEY LIST''' statement lists the softkey strings assigned to each of the function keys down the left side of the screen. +#REDIRECT [[KEY n#Function_Soft_Key_Strings_.281_to_10.2C_30_.26_31.29]] + +The [[KEY LIST]] statement lists the soft key strings assigned to each of the function keys down the left side of the screen. {{PageSyntax}} -:: KEY LIST +: [[KEY LIST]] -:: KEY {ON|OFF} - - -''Description:'' -* Instead of using an [[ON KEY(n)]] [[GOSUB]] statement, Function keys F1 to F12 can be assigned a "soft key" string value to return. -* '''[[KEY n]], text$''' defines a literal or variable [[STRING]] "soft key" Function key return value. -{{WhiteStart}} '''KEY 1, "Help"''' 'will return the string "Help" to an [[INPUT]] variable when F1 is pressed{{WhiteEnd}} -* ''n%'' is the number 1 to 10(F1 to F10), 30 or 31(F11 or F12) of the function key to assign the soft key string. -* [[KEY LIST]] displays each of the 12 softkey '''function key'''(F1 to F12) string values going down the screen. -* '''KEY {ON|OFF}''' turns the softkey Function key display of F1 to F10 at the bottom of the screen ON or OFF. -* '''Note: Soft key values cannot be assigned to KEY numbers 11 through 29 or an [[ERROR Codes|"Illegal Function call" error]] will occur!''' +{{PageDescription}} +* [[KEY LIST]] displays each of the 12 softkey '''function key''' (F1 to F12) string values going down the screen. +{{PageExamples}} ''Example 1:'' Displaying the current '''KEY LIST''' string assignments to the Function keys. {{CodeStart}} '' '' {{Cl|KEY n|KEY}} 1, "Help" @@ -78,7 +72,7 @@ Press F10 to turn display off! Compile :''Explanation:'' The [[INPUT]] variable will hold the string value as if it was typed in and entered. "Quit" will KEY OFF bottom display. -''See also:'' +{{PageSeeAlso}} * [[KEY n]], [[KEY(n)]], * [[ON KEY(n)]] * [[_KEYHIT]], [[_KEYDOWN]] diff --git a/internal/help/KEY_n.txt b/internal/help/KEY_n.txt index b1d6046f8..721663118 100644 --- a/internal/help/KEY_n.txt +++ b/internal/help/KEY_n.txt @@ -1,28 +1,23 @@ -The '''KEY n''' statement is used to assign a "softkey" string or a flag and scan code to a key or display function soft key assignments. - -{| align="Right" - | __TOC__ - |} - +The [[KEY n]] statement is used to assign a "soft key" string or a flag and scan code to a function key or display function soft key assignments. {{PageSyntax}} -:: '''KEY ''n%'', ''text_string$''''' +: '''KEY ''n%'', ''textString$''''' -:: '''KEY ''n%'', CHR$(''keyflag%'') + CHR$(''scancode'')''' +: '''KEY ''n%'', CHR$(''keyFlag%'') + CHR$(''scanCode'')''' ==Function Soft Key Strings (1 to 10, 30 & 31)== -<center>'''Assigning "Softkey" [[STRING]] values to Function key press events'''</center> +<center>'''Assigning "Softkey" [[STRING]] values to function key press events'''</center> -* n% is the number 1 to 10(F1 to F10), 30 or 31(F11 or F12) of the function key to assign the soft key string. +* n% is the number 1 to 10 (F1 to F10), 30 or 31 (F11 or F12) of the function key to assign the soft key string. * Instead of using an [[ON KEY(n)]] [[GOSUB]] statement, Function keys F1 to F12 can be assigned a "soft key" string value to return. -* '''KEY n, text$''' defines a literal or variable [[STRING]] "soft key" Function key return value. +* {{InlineCode}}KEY n, text${{InlineCodeEnd}} defines a literal or variable [[STRING]] "soft key" function key return value. {{WhiteStart}} '''KEY 1, "Help"''' 'returns the string "Help" to [[INPUT]] variable when F1 is pressed{{WhiteEnd}} -* [[KEY LIST]] displays each of the 12 softkey '''function key'''(F1 to F12) string values going down left side of screen. +* [[KEY LIST]] displays each of the 12 softkey '''function key''' (F1 to F12) string values going down left side of screen. * [[KEY LIST|KEY {ON|OFF}]] displays or hides the softkey values of function keys F1 to F10 at the bottom of the screen. @@ -32,6 +27,7 @@ The '''KEY n''' statement is used to assign a "softkey" string or a fl * Soft Key [[STRING]]s cannot be assigned to these key numbers! * To use the extended arrow keys on a keyboard use the Extended Key Flag 128 with corresponding Scan code as User Defined Keys. + ==User Defined Keys (15 to 29)== <center>'''Assigning user defined keys or combinations with: KEY n, CHR$(keyflag) + CHR$(scancode)'''</center> @@ -79,7 +75,7 @@ The '''KEY n''' statement is used to assign a "softkey" string or a fl <center>'''Trapping Extended keys (Insert, Home, Page Up, Right Ctrl, R.Alt, and cursor arrow pad)'''</center> -* On a 101-key keyboard, you can trap any of the keys on the dedicated cursorpad by assigning the string to any of the keynumber values from 15 to 25 using the 128 keyboard flag. The cursor arrows are NOT the same as the pre-assigned number pad arrows: +* On a 101-key keyboard, you can trap any of the keys on the dedicated cursorpad by assigning the string to any of the keynumber values from 15 to 25 using the 128 keyboard flag. The cursor arrows are not the same as the pre-assigned number pad arrows: {{WhiteStart}} '''KEY n, [[CHR$]](128) + [[CHR$]](scancode) ' where n = 15 to 29. See: [[Scancodes]]''' KEY 15, CHR$(128) + CHR$(75) 'left arrow cursor pad  @@ -95,6 +91,7 @@ The '''KEY n''' statement is used to assign a "softkey" string or a fl <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> + ==Examples== @@ -205,8 +202,8 @@ COLOR 11: LOCATE 11, 26: PRINT "Down number pad " <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> -==References== -''See also:'' + +{{PageSeeAlso}} * [[KEY LIST]], [[ON KEY(n)]] * [[KEY(n)]], [[INKEY$]] * [[_KEYHIT]], [[_KEYDOWN]] diff --git a/internal/help/KILL.txt b/internal/help/KILL.txt index 72d32db69..c9cca70ca 100644 --- a/internal/help/KILL.txt +++ b/internal/help/KILL.txt @@ -1,32 +1,30 @@ -The '''KILL''' statement deletes a file on a relative path designated by a [[STRING]] value or variable. - +The [[KILL]] statement deletes a file designated by a [[STRING]] value or variable. {{PageSyntax}} -:: KILL filespec$ +: [[KILL]] {{Parameter|fileSpec$}} -* Filespec is a literal or variable string path and filename. Wildcards * and ? can be used but '''be careful!''' +* {{Parameter|fileSpec$}} is a literal or variable string path and filename. Wildcards * and ? can be used with caution. ::'''*''' denotes one or more wildcard letters of a name or extension ::'''?''' denotes one wildcard letter of a name or extension -* Path can be relative to program's current location or use an absolute path from the root drive. -* KILL cannot remove an [[OPEN]] file. The program MUST [[CLOSE]] it first. -* If the path or file does not exist, a "File not found" or "Path not found" [[ERROR Codes|error]] will result. -* [[SHELL]] ''"DEL /Q " + filename$'' does the same without a prompt or verification for wildcard deletions. -* [[SHELL]] ''"DEL /P " + filename$'' will ask for user verification. -* Cannot delete folders or directories! Use [[RMDIR]] to remove empty folders only! -* '''Warning! Files deleted in DOS or QB64 will NOT go to the Recycle Bin and they CANNOT be restored!''' +* {{Parameter|fileSpec$}} can include a path that can be either relative to the program's current location or absolute, from the root drive. +* [[KILL]] cannot remove an [[OPEN]] file. The program must [[CLOSE]] it first. +* If the path or file does not exist, a "File not found" or "Path not found" [[ERROR Codes|error]] will result. See [[_FILEEXISTS]]. +* {{InlineCode}}[[SHELL]] "DEL /Q " + fileName${{InlineCodeEnd}} does the same without a prompt or verification for wildcard deletions. +* {{InlineCode}}[[SHELL]] "DEL /P " + fileName${{InlineCodeEnd}} will ask for user verification. +* Cannot delete folders or directories. Use [[RMDIR]] to remove empty folders. +* '''Warning: files deleted with [[KILL]] will not go to the Recycle Bin and they cannot be restored.''' - -''Example:'' +{{PageExamples}} {{CodeStart}} KILL "C:\Qbasic\data\2000data.dat" {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[RMDIR]], [[FILES]], [[SHELL]], [[OPEN]] * [[CHDIR]], [[MKDIR]], [[NAME]] * [[_FILEEXISTS]], [[_DIREXISTS]] diff --git a/internal/help/Keyword_Reference_-_Alphabetical.txt b/internal/help/Keyword_Reference_-_Alphabetical.txt index 3e9953883..f19325c26 100644 --- a/internal/help/Keyword_Reference_-_Alphabetical.txt +++ b/internal/help/Keyword_Reference_-_Alphabetical.txt @@ -1,5 +1,5 @@ __NOTOC__ -<div id="toc"><p style="text-align: center"><br> '''Alphabetical QB64 Keyword Listings''' <br><br>     '''QB 64:'''  [[#uA|_A]] [[#uB|_B]] [[#uC|_C]] [[#uD|_D]] [[#uE|_E]] [[#uF|_F]] [[#uG|_G]] [[#uH|_H]] [[#uI|_I]] [[#uK|_K]] [[#uL|_L]] [[#uM|_M]] [[#uN|_N]] [[#uO|_O]] [[#uP|_P]] [[#uR|_R]] [[#uS|_S]] [[#uT|_T]] [[#uU|_U]] [[#uV|_V]] [[#uW|_W]]                <br><br>'''Qbasic:'''  [[#A|A]]   [[#B|B]]   [[#C|C]]   [[#D|D]]   [[#E|E]]    [[#F|F]]   [[#G|G]]   [[#H|H]]    [[#I| I]]    [[#K|K]]   [[#L|L]]   [[#M|M]]   [[#N|N]]    [[#O|O]]   [[#P|P]]    [[#R|R]]   [[#S|S]]    [[#T|T]]   [[#U|U]]   [[#V|V]]   [[#W|W]]   [[#X|X]]   <br><br>'''OpenGL:'''   [[#glA|A]]    [[#glB|B]]    [[#glC|C]]    [[#glD|D]]    [[#glE|E]]     [[#glF|F]]    [[#glG|G]]    [[#glH|H]]    [[#glI| I  ]]   [[#glL|L]]    [[#glM|M]]    [[#glN|N]]     [[#glO|O]]    [[#glP|P]]     [[#glR|R]]    [[#glS|S]]     [[#glT|T]]    [[#glV|V]]       <br><br> [[#symbols|Symbols]] '''   -   ''' [[#references|References]]<br><br>[[Full Story|{{small|Menu Created by Cyperium}} ]]</p></div> +<div id="toc"><p style="text-align: center"><br> '''Alphabetical QB64 Keyword Listings''' <br><br>     '''QB 64:'''  [[#uA|_A]] [[#uB|_B]] [[#uC|_C]] [[#uD|_D]] [[#uE|_E]] [[#uF|_F]] [[#uG|_G]] [[#uH|_H]] [[#uI|_I]] [[#uK|_K]] [[#uL|_L]] [[#uM|_M]] [[#uN|_N]] [[#uO|_O]] [[#uP|_P]] [[#uR|_R]] [[#uS|_S]] [[#uT|_T]] [[#uU|_U]] [[#uV|_V]] [[#uW|_W]]                <br><br>'''QBasic:'''  [[#A|A]]   [[#B|B]]   [[#C|C]]   [[#D|D]]   [[#E|E]]    [[#F|F]]   [[#G|G]]   [[#H|H]]    [[#I| I]]    [[#K|K]]   [[#L|L]]   [[#M|M]]   [[#N|N]]    [[#O|O]]   [[#P|P]]    [[#R|R]]   [[#S|S]]    [[#T|T]]   [[#U|U]]   [[#V|V]]   [[#W|W]]   [[#X|X]]   <br><br>'''OpenGL:'''   [[#glA|A]]    [[#glB|B]]    [[#glC|C]]    [[#glD|D]]    [[#glE|E]]     [[#glF|F]]    [[#glG|G]]    [[#glH|H]]    [[#glI| I  ]]   [[#glL|L]]    [[#glM|M]]    [[#glN|N]]     [[#glO|O]]    [[#glP|P]]     [[#glR|R]]    [[#glS|S]]     [[#glT|T]]    [[#glV|V]]       <br><br> [[#symbols|Symbols]] '''   -   ''' [[#references|References]]<br><br>[[Full Story|{{small|Menu Created by Cyperium}} ]]</p></div> @@ -19,15 +19,11 @@ __NOTOC__ <p style="text-align: center"> Offline WIKI Reference contributed by OlDosLover.</p> -<p style="text-align: center">If '''FIREFOX''' does not copy page example code correctly use another browser or download our '''Code Fix Addon''' :</p> - -<center>[[Mozilla FireFox Code Copy Add On]] (Information)</center> - <p style="text-align: center">For comments or suggestions about this WIKI goto the [http://www.qb64.net/forum/index.php?board=14.0 QB64 Community Development Forum].</p> <center>'''[[Known QB64 Issues]]'''</center> -<center> '''If code examples only display partial code, use the browser Refresh button!'''</center> +<center> '''If code examples only display partial code, use the browser Refresh button'''</center> <center>[[Main Page|Main Page with Appendix and Tutorials]]</center> @@ -36,7 +32,6 @@ __NOTOC__ ==QB64 specific keywords:== <p style="text-align: center">The underscore prefix is reserved for QB64 _KEYWORDS only.</p> -<p style="text-align: center">Listed _KEYWORDS and un-commented $[[Metacommand]]s only work when compiled in QB64.</p> <div id = "uA">_A</div> * [[_ACOS]] (function) {{text|arccosine function returns the angle in radians based on an input [[COS]]ine value range from -1 to 1.}} @@ -51,6 +46,7 @@ __NOTOC__ * [[_ATAN2]] (function) {{text|Returns the principal value of the [[ATN|arc tangent]] of y/x, expressed in radians.}} * [[_ATANH]] (function) {{text|Returns the arc hyperbolic tangent of x, expressed in radians.}} * [[_AUTODISPLAY]] (statement) {{text|enables the automatic display of the screen image changes previously disabled by [[_DISPLAY]].}} +* [[_AUTODISPLAY (function)]] {{text|returns the current display mode as true (-1) if automatic or false (0) if per request using [[_DISPLAY]].}} * [[_AXIS]] (function) {{text|returns a [[SINGLE]] value between -1 and 1 indicating the maximum distance from the device axis center, 0.}} ---- @@ -61,6 +57,8 @@ __NOTOC__ * [[_BIT]] (` numerical type) {{text|can return only signed values of 0 (bit off) and -1 (bit on). Unsigned 0 or 1.}} * [[_BLEND]] (statement) {{text|statement turns on 32 bit alpha blending for the current image or screen mode and is default.}} * [[_BLEND (function)]] {{text|returns -1 if enabled or 0 if disabled by [[_DONTBLEND]] statement.}} +* [[_BLINK]] (statement) {{text|statement turns blinking colors on/off in SCREEN 0}} +* [[_BLINK (function)]] {{text|returns -1 if enabled or 0 if disabled by [[_BLINK]] statement.}} * [[_BLUE]] (function) {{text|function returns the palette or the blue component intensity of a 32-bit image color.}} * [[_BLUE32]] (function) {{text|returns the blue component intensity of a 32-bit color value.}} * [[_BUTTON]] (function) {{text|returns -1 when a controller device button is pressed and 0 when button is released.}} @@ -73,20 +71,23 @@ __NOTOC__ <div id = "uC">_C</div> -* [[$CHECKING]] (QB64 C++ [[Metacommand]]) {{text|turns event error checking OFF or ON. Do not comment or REM.}} +* [[$CHECKING]] (QB64 C++ [[Metacommand]]) {{text|turns event error checking OFF or ON.}} * [[_CEIL]] (function) {{text|Rounds x upward, returning the smallest integral value that is not less than x.}} * [[_CLEARCOLOR (function)]] {{text|returns the current transparent color of an image.}} * [[_CLEARCOLOR]] (statement) {{text|sets a specific color index of an image to be transparent}} * [[_CLIP]] ([[PUT (graphics statement)|PUT]] graphics option) {{text|allows placement of an image partially off of the screen.}} * [[_CLIPBOARD$]] (function) {{text|returns the operating system's clipboard contents as a [[STRING]].}} * [[_CLIPBOARD$ (statement)]] {{text|sets and overwrites the [[STRING]] value in the operating system's clipboard.}} +* [[_CLIPBOARDIMAGE (function)]] {{text|pastes an image from the clipboard into a new QB64 image in memory.}} +* [[_CLIPBOARDIMAGE]] {{text|(statement) copies a valid QB64 image to the clipboard.}} * [[_COMMANDCOUNT]] (function) {{text|returns the number of arguments passed to the compiled program from the command line.}} * [[_CONNECTED]] (function) {{text|returns the status of a TCP/IP connection handle.}} * [[_CONNECTIONADDRESS$]] (TCP/IP function) {{text|returns a connected user's STRING IP address value using the handle.}} -* [[$CONSOLE]] (QB64 [[Metacommand]]) {{text|creates a console window that can be used throughout a program. Do not comment!}} +* [[$CONSOLE]] (QB64 [[Metacommand]]) {{text|creates a console window that can be used throughout a program.}} * [[_CONSOLE]] (statement) {{text|used to turn a console window OFF or ON or to designate [[_DEST]] _CONSOLE for output.}} * [[_CONSOLETITLE]] (statement) {{text|creates the title of the console window using a literal or variable [[STRING|string]].}} -* [[_CONTROLCHR]] (statement) {{text|[[OFF]] allows the control characters to be used as text characters. [[ON]](default) can use them as commands.}} +* [[_CONTINUE]] (statement) {{text|skips the remaining lines in a control block (DO/LOOP, FOR/NEXT or WHILE/WEND)}} +* [[_CONTROLCHR]] (statement) {{text|[[OFF]] allows the control characters to be used as text characters. [[ON]] (default) can use them as commands.}} * [[_CONTROLCHR (function)]] {{text| returns the current state of _CONTROLCHR as 1 when OFF and 0 when ON.}} * [[_COPYIMAGE]] (function) {{text|copies an image handle value to a new designated handle.}} * [[_COPYPALETTE]] (statement) {{text|copies the color palette intensities from one 4 or 8 BPP image to another image.}} @@ -107,11 +108,11 @@ __NOTOC__ * [[_D2G]] (function) {{text|converts degrees to gradient angle values.}} * [[_D2R]] (function) {{text|converts degrees to radian angle values.}} * [[DECLARE LIBRARY|DECLARE LIBRARY (QB64 statement block)]] {{text|declares a C++, SDL or Operating System [[SUB]] or [[FUNCTION]] to be used.}} -* [[DECLARE DYNAMIC LIBRARY|DECLARE DYNAMIC LIBRARY (QB64 statement)]] {{text|declares DYNAMIC, CUSTOMTYPE or STATIC library(DLL) [[SUB]] or [[FUNCTION]].}} +* [[DECLARE DYNAMIC LIBRARY|DECLARE DYNAMIC LIBRARY (QB64 statement)]] {{text|declares DYNAMIC, CUSTOMTYPE or STATIC library (DLL) [[SUB]] or [[FUNCTION]].}} * [[_DEFAULTCOLOR]] (function) {{text|returns the current default text color for an image handle or page.}} * [[_DEFINE]] (statement) {{text|defines a range of variable names according to their first character as a data type.}} * [[_DELAY]] (statement) {{text|suspends program execution for a [[SINGLE]] number of seconds.}} -* [[_DEPTHBUFFER]] (statement) {{text|enables, disables, locks or clears depth buffering in GL.}} +* [[_DEPTHBUFFER]] (statement) {{text|enables, disables, locks or clears depth buffering.}} * [[_DESKTOPHEIGHT]] (function) {{text|returns the height of the desktop (not program window).}} * [[_DESKTOPWIDTH]] (function) {{text|returns the width of the desktop (not program window).}} * [[_DEST]] (statement) {{text|sets the current write image or [[SCREEN]] page destination for prints or graphics.}} @@ -119,10 +120,11 @@ __NOTOC__ * [[_DEVICE$]] (function) {{text|returns a [[STRING]] expression listing a designated numbered input device name and types of input.}} * [[_DEVICEINPUT]] (function) {{text|returns the [[_DEVICES]] number of an [[_AXIS]], [[_BUTTON]] or [[_WHEEL]] event.}} * [[_DEVICES]] (function) {{text|returns the number of input devices found on a computer system including the keyboard and mouse.}} +* [[_DIR$]] (function) {{text|returns common paths in Windows only, like My Documents, My Pictures, My Music, Desktop.}} * [[_DIREXISTS]] (function) {{text|returns -1 if the Directory folder name [[STRING|string]] parameter exists. Zero if it does not.}} * [[_DISPLAY]] (statement) {{text|turns off the [[_AUTODISPLAY|automatic display]] while only displaying the screen changes when called.}} * [[_DISPLAY (function)]] {{text|returns the handle of the current image that is displayed on the screen.}} -* [[_DISPLAYORDER]] (GL statement) {{text|designates the order to render software, hardware and custom-opengl-code.}} +* [[_DISPLAYORDER]] (statement) {{text|designates the order to render software, hardware and custom-opengl-code.}} * [[_DONTBLEND]] (statement) {{text|statement turns off default [[_BLEND]] 32 bit [[_ALPHA|alpha]] blending for the current image or screen.}} * [[_DONTWAIT]] ([[SHELL]] action) {{text|specifies that the program should not wait until the shelled command/program is finished.}} @@ -131,10 +133,11 @@ __NOTOC__ <div id = "uE">_E</div> -* [[$ELSE]] (QB64 Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler. Do not comment or REM.}} -* [[$ELSEIF]] (QB64 Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler. Do not comment or REM.}} -* [[$END IF]] (QB64 Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler. Do not comment or REM.}} +* [[$ELSE]] (Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler.}} +* [[$ELSEIF]] (Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler.}} +* [[$END IF]] (Pre-Compiler [[Metacommand]]) {{text|used in conjunction with $IF for the precompiler.}} * [[_ERRORLINE]] (function) {{text|returns the source code line number that caused the most recent runtime error.}} +* [[$EXEICON]] (Pre-Compiler [[Metacommand]]) {{text|used with a .ICO icon file name to embed the image into the QB64 executable.}} * [[_EXIT (function)]] {{text|prevents a user exit and indicates if a user has clicked the close X window button or CTRL + BREAK.}} <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> @@ -151,7 +154,7 @@ __NOTOC__ * [[_FONTWIDTH]] (function) {{text|returns the current text or font width.}} * [[_FREEFONT]] (statement) {{text|releases the current font handle from memory.}} * [[_FREEIMAGE]] (statement) {{text|releases a designated image handle from memory.}} -* [[_FREETIMER]] (function) {{text|returns an unused timer number value to use with [[ON TIMER (n)]].}} +* [[_FREETIMER]] (function) {{text|returns an unused timer number value to use with [[ON TIMER(n)]].}} * [[_FULLSCREEN]] (statement) {{text|sets the program window to full screen or OFF. Alt + Enter does it manually.}} * [[_FULLSCREEN (function)]] {{text|returns the fullscreen mode in use by the program.}} @@ -179,8 +182,10 @@ __NOTOC__ <div id = "uI">_I</div> -* [[$IF]] (QB64 Pre-Compiler [[Metacommand]]) {{text|used to set an IF condition for the precompiler. Do not comment or REM.}} -* [[_ICON]] (statement) {{text|designates a [[_LOADIMAGE]] image file handle to be used as the program's icon. (Icons can be used in GL only!)}} +* [[$IF]] (Pre-Compiler [[Metacommand]]) {{text|used to set an IF condition for the precompiler.}} +* [[_ICON]] (statement) {{text|designates a [[_LOADIMAGE]] image file handle to be used as the program's icon or loads the embedded icon (see [[$EXEICON]]).}} +* [[_INCLERRORFILE$]] {function) {{text|returns the name of the original source code $INCLUDE module that caused the most recent error.}} +* [[_INCLERRORLINE]] (function) {{text|returns the line number in an included file that caused the most recent error.}} * [[_INTEGER64]] (&& numerical type) {{text|can hold whole numerical values from -9223372036854775808 to 9223372036854775807.}} <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> @@ -199,7 +204,7 @@ __NOTOC__ <div id = "uL">_L</div> -* [[$LET]] (QB64 Pre-Compiler [[Metacommand]]) {{text|used to set a flag variable for the precompiler. Do not comment or REM.}} +* [[$LET]] (Pre-Compiler [[Metacommand]]) {{text|used to set a flag variable for the precompiler.}} * [[_LASTAXIS]] (function) {{text|returns the number of axis available on a specified number device listed by [[_DEVICE$]].}} * [[_LASTBUTTON]] (function) {{text|returns the number of buttons available on a specified number device listed by [[DEVICE$]].}} * [[_LASTWHEEL]] (function) {{text|returns the number of scroll wheels available on a specified number device listed by [[_DEVICE$]].}} @@ -215,20 +220,20 @@ __NOTOC__ <div id = "uM">_M</div> * [[_MAPTRIANGLE]] (statement) {{text|maps a triangular image source area to put on a destination area.}} * [[_MAPUNICODE]] (statement) {{text|maps a [[Unicode]] value to an [[ASCII]] code number.}} -* [[_MAPUNICODE (function)]] {{text|returns the [[Unicode]](UTF32) code point value of a mapped [[ASCII]] character code.}} +* [[_MAPUNICODE (function)]] {{text|returns the [[Unicode]] (UTF32) code point value of a mapped [[ASCII]] character code.}} * [[_MEM (function)]] {{text|returns [[_MEM]] block referring to the largest continuous memory region beginning at a designated variable's offset.}} * [[_MEM]] (variable type) {{text|contains read only dot elements for the OFFSET, SIZE, TYPE and ELEMENTSIZE of a block of memory.}} * [[_MEMCOPY]] (statement) {{text|copies a value from a designated OFFSET and SIZE [[TO]] a block of memory at a designated OFFSET.}} * [[_MEMELEMENT]] (function) {{text|returns a [[_MEM]] block referring to a variable's memory (but not past it).}} * [[_MEMEXISTS]] (function) {{text|verifies that a memory block exists for a memory variable name or returns zero.}} * [[_MEMFILL]] (statement) {{text|fills a designated memory block OFFSET with a certain SIZE and TYPE of value.}} -* [[_MEMFREE]] (statement) {{text|frees a designated memory block in a program. Only free memory blocks once!}} +* [[_MEMFREE]] (statement) {{text|frees a designated memory block in a program. Only free memory blocks once.}} * [[_MEMGET]] (statement) {{text|reads a value from a designated memory block at a designated OFFSET}} * [[_MEMGET (function)]] {{text|returns a value from a designated memory block and OFFSET using a designated variable [[TYPE]].}} * [[_MEMIMAGE]] (function) {{text|returns a [[_MEM]] block referring to a designated image handle's memory}} * [[_MEMNEW]] (function) {{text|allocates new memory with a designated SIZE and returns a [[_MEM]] block referring to it.}} * [[_MEMPUT]] (statement) {{text|places a designated value into a designated memory block OFFSET}} -* [[_SCREENMOVE|_MIDDLE]](_SCREENMOVE option) {{text|centers the program window on the desktop in any screen resolution.}} +* [[_SCREENMOVE|_MIDDLE]] (_SCREENMOVE parameter) {{text|centers the program window on the desktop in any screen resolution.}} * [[_MK$]] (function) {{text|converts a numerical value to a designated [[ASCII]] [[STRING]] value.}} * [[_MOUSEBUTTON]] (function) {{text|returns the status of a designated mouse button.}} * [[_MOUSEHIDE]] (statement) {{text|hides the mouse pointer from view}} @@ -237,7 +242,7 @@ __NOTOC__ * [[_MOUSEMOVEMENTX]] (function) {{text|returns the relative horizontal position of the mouse cursor compared to the previous position.}} * [[_MOUSEMOVEMENTY]] (function) {{text|returns the relative vertical position of the mouse cursor compared to the previous position.}} * [[_MOUSEPIPEOPEN]] (function) {{text|creates a pipe handle value for a mouse when using a virtual keyboard.}} -* [[_MOUSESHOW]] (statement) {{text|displays the mouse cursor after it has been hidden or can change the cursor shape in GL.}} +* [[_MOUSESHOW]] (statement) {{text|displays the mouse cursor after it has been hidden or can change the cursor shape.}} * [[_MOUSEWHEEL]] (function) {{text|returns the number of mouse scroll wheel "clicks" since last read.}} * [[_MOUSEX]] (function) {{text|returns the current horizontal position of the mouse cursor.}} * [[_MOUSEY]] (function) {{text|returns the current vertical position of the mouse cursor.}} @@ -256,10 +261,11 @@ __NOTOC__ <div id = "uO">_O</div> * [[_OFFSET (function)]] {{text|returns the memory offset of a variable when used with [[DECLARE LIBRARY]] or [[_MEM]] only.}} -* [[_OFFSET]](%& numerical type) {{text|can be used store the value of an offset in memory when using [[DECLARE LIBRARY]] or [[MEM]] only.}} +* [[_OFFSET]] (%& numerical type) {{text|can be used store the value of an offset in memory when using [[DECLARE LIBRARY]] or [[MEM]] only.}} * [[_OPENCLIENT]] (TCP/IP function) {{text|connects to a Host on the Internet as a Client and returns the Client status handle.}} * [[_OPENCONNECTION]] (TCP/IP function) {{text|open's a connection from a client that the host has detected and returns a status handle.}} * [[_OPENHOST]] (TCP/IP function) {{text|opens a Host and returns a Host status handle.}} +* [[OPTION _EXPLICIT]] (Pre-compiler directive) {{text|instructs the compiler to require variable declaration with [[DIM]] or an equivalent statement.}} * [[_OS$]] (function) {{text|returns the QB64 compiler version in which the program was compiled as [WINDOWS], [LINUX] or [MACOSX] and [32BIT] or [64BIT].}} @@ -289,11 +295,11 @@ __NOTOC__ * [[_R2G]] (function) {{text|converts radians to gradient angle values.}} * [[_RED]] (function) {{text|function returns the palette or the red component intensity of a 32-bit image color.}} * [[_RED32]] (function) {{text|returns the red component intensity of a 32-bit color value.}} -* [[$RESIZE]] ([[Metacommand]]) {{text|used with ON allows a user to resize the GL program window where OFF does not. Do not comment!}} +* [[$RESIZE]] ([[Metacommand]]) {{text|used with ON allows a user to resize the program window where OFF does not.}} * [[_RESIZE]] (statement) {{text|sets resizing of the window ON or OFF and sets the method as _STRETCH or _SMOOTH.}} -* [[_RESIZE (function)]] {{text|returns -1 when a program user wants to resize the GL program screen.}} -* [[_RESIZEHEIGHT]] (function) {{text|returns the requested new user GL screen height when [[$RESIZE]]:ON allows it.}} -* [[_RESIZEWIDTH]] (function) {{text|returns the requested new user GL screen width when [[$RESIZE]]:ON allows it.}} +* [[_RESIZE (function)]] {{text|returns -1 when a program user wants to resize the program screen.}} +* [[_RESIZEHEIGHT]] (function) {{text|returns the requested new user screen height when [[$RESIZE]]:ON allows it.}} +* [[_RESIZEWIDTH]] (function) {{text|returns the requested new user screen width when [[$RESIZE]]:ON allows it.}} * [[_RGB]] (function) {{text|returns the closest palette index OR the [[LONG]] 32 bit color value in 32 bit screens.}} * [[_RGB32]] (function) {{text|returns the [[LONG]] 32 bit color value in 32 bit screens only}} * [[_RGBA]] (function) {{text|returns the closest palette index OR the [[LONG]] 32 bit color value in 32 bit screens with the [[ALPHA]]}} @@ -310,14 +316,14 @@ __NOTOC__ * [[Mathematical_Operations#Derived_Mathematical_Functions|_SECH]] (function) {{text|Returns the hyperbolic secant. http://mathworld.wolfram.com/HyperbolicSecant.html}} * [[_SCREENCLICK]] (statement) {{text|simulates clicking on a point on the desktop screen with the left mouse button.}} * [[_SCREENEXISTS]] (function) {{text|returns a -1 value once a screen has been created.}} -* [[$SCREENHIDE]] (QB64 [[Metacommand]]) {{text|hides the program window from view. Do not comment!}} +* [[$SCREENHIDE]] ([QB64 [Metacommand]]) {{text|hides the program window from view.}} * [[_SCREENHIDE]] (statement) {{text|hides the program window from view.}} * [[_SCREENICON (function)]] {{text|returns -1 or 0 to indicate if the window has been minimized to an icon on the taskbar.}} * [[_SCREENICON]] (statement) {{text|minimizes the program window to an icon on the taskbar.}} * [[_SCREENIMAGE]] (function) {{text|creates an image of the current desktop and returns an image handle.}} * [[_SCREENMOVE]] (statement) {{text|positions program window on the desktop using designated coordinates or the _MIDDLE option.}} * [[_SCREENPRINT]] (statement) {{text|simulates typing text into a Windows program using the keyboard.}} -* [[$SCREENSHOW]] (QB64 [[Metacommand]]) {{text|displays that program window after it was hidden by [[$SCREENHIDE]]. Do not comment!}} +* [[$SCREENSHOW]] (QB64 [[Metacommand]]) {{text|displays that program window after it was hidden by [[$SCREENHIDE]].}} * [[_SCREENSHOW]] (statement) {{text|displays the program window after it has been hidden by [[_SCREENHIDE]].}} * [[_SCREENX]] (function) {{text|returns the program window's upper left corner horizontal position on the desktop.}} * [[_SCREENY]] (function) {{text|returns the program window's upper left corner vertical position on the desktop.}} @@ -325,16 +331,16 @@ __NOTOC__ * [[_SETALPHA]] (statement) {{text|sets the alpha channel transparency level of some or all of the pixels of an image.}} * [[_SHELLHIDE]] (function) {{text|returns the code sent by a program exit using [[END]] or [[SYSTEM]] followed by an [[INTEGER]] value.}} * [[Mathematical_Operations|_SINH]] (function) {{text|Returns the hyperbolic sine of x radians.}} -* [[_SNDBAL]] (statement) {{text|attempts to set the balance or 3D position of a sound file with the SYNC capability.}} +* [[_SNDBAL]] (statement) {{text|attempts to set the balance or 3D position of a sound file.}} * [[_SNDCLOSE]] (statement) {{text|frees and unloads an open sound using the sound handle created by [[_SNDOPEN]].}} * [[_SNDCOPY]] (function) {{text|copies a sound handle value to a new designated handle.}} -* [[_SNDGETPOS]] (function) {{text|returns the current playing position in seconds from a sound file with the SETPOS capability.}} -* [[_SNDLEN]] (function) {{text|returns the length of a sound in seconds from a sound file with the LEN capability.}} +* [[_SNDGETPOS]] (function) {{text|returns the current playing position in seconds from a sound file.}} +* [[_SNDLEN]] (function) {{text|returns the length of a sound in seconds from a sound file.}} * [[_SNDLIMIT]] (statement) {{text|stops playing a sound after it has been playing for a set number of seconds.}} * [[_SNDLOOP]] (statement) {{text|plays a sound repeatedly until [[_SNDSTOP]] is used.}} * [[_SNDOPEN]] (function) {{text|loads a sound file and returns a sound handle.}} -* [[_SNDOPENRAW]] (GL function) {{text|opens a new channel to shove [[_SNDRAW]] content into without mixing.}} -* [[_SNDPAUSE]] (statement) {{text|stops playing a sound file that has the PAUSE capability until resumed.}} +* [[_SNDOPENRAW]] (function) {{text|opens a new channel to shove [[_SNDRAW]] content into without mixing.}} +* [[_SNDPAUSE]] (statement) {{text|stops playing a sound file until resumed.}} * [[_SNDPAUSED]] (function) {{text|returns the current pause status of a sound file handle.}} * [[_SNDPLAY]] (statement) {{text|plays a sound file handle that was created by [[_SNDOPEN]] or [[_SNDCOPY]].}} * [[_SNDPLAYCOPY]] (statement) {{text|copies a sound handle, plays it and automatically closes the copy when done.}} @@ -342,11 +348,11 @@ __NOTOC__ * [[_SNDPLAYING]] (function) {{text|returns the current playing status of a sound handle.}} * [[_SNDRATE]] (function) {{text|returns the sound card sample rate to set [[_SNDRAW]] durations.}} * [[_SNDRAW]] (statement) {{text|creates mono or stereo sounds from calculated wave frequency values.}} -* [[_SNDRAWDONE]] (GL statement) {{text|pads a [[_SNDRAW]] stream so the final (partially filled) buffer section is played.}} +* [[_SNDRAWDONE]] (statement) {{text|pads a [[_SNDRAW]] stream so the final (partially filled) buffer section is played.}} * [[_SNDRAWLEN]] (function) {{text|returns a value until the [[_SNDRAW]] buffer is empty.}} * [[_SNDSETPOS]] (statement) {{text|sets the playing position of a sound handle.}} * [[_SNDSTOP]] (statement) {{text|stops playing a sound handle.}} -* [[_SNDVOL]] (statement) {{text|sets the volume of a sound file handle that has the VOL capability.}} +* [[_SNDVOL]] (statement) {{text|sets the volume of a sound file handle.}} * [[_SOURCE]] (statement) {{text|sets the source image handle.}} * [[_SOURCE (function)]] {{text|returns the present source image handle value.}} * [[_STARTDIR$]] (function) {{text|returns the user's program calling path as a [[STRING]].}} @@ -362,6 +368,7 @@ __NOTOC__ * [[Mathematical_Operations|_TANH]] (function) {{text|Returns the hyperbolic tangent of x radians.}} * [[_TITLE]] (statement) {{text|sets the program title [[STRING|string]] value.}} +* [[_TITLE$]] (function) {{text|gets the program title [[STRING|string]] value.}} ---- @@ -377,7 +384,8 @@ __NOTOC__ <div id = "uV">_V</div> -* [[$VIRTUALKEYBOARD]] (QB64 metacommand) {{text|turns the virtual keyboard ON or OFF in Android device programs. Do not comment!}} +* [[$VERSIONINFO]] ([[Metacommand]]) {{text|adds metadata to Windows only binaries for identification purposes across the OS.}} +* [[$VIRTUALKEYBOARD]] ([[Metacommand]]) {{text|turns the virtual keyboard ON or OFF for use in touch-enabled devices}} ---- @@ -387,6 +395,8 @@ __NOTOC__ * [[_WHEEL]] (function) {{text|returns -1 when a control device wheel is scrolled up and 1 when scrolled down. Zero indicates no activity.}} * [[_WIDTH (function)]] {{text|returns the width of a [[SCREEN]] or image handle.}} +* [[_WINDOWHANDLE]] (function) {{text|returns the window handle assigned to the current program by the OS. Windows-only.}} +* [[_WINDOWHASFOCUS]] (function) {{text|returns true (-1) if the current program's window has focus. Windows-only.}} <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> @@ -394,7 +404,7 @@ __NOTOC__ <center>([[Keyword Reference - Alphabetical#QB64 specific keywords:|Go to Top of QB64 specific keywords]])</center> ==Original QBasic keywords:== -'''<p style="text-align: center">These Qbasic keywords (with a few noted exceptions) will work in all versions of QB64.</p>''' +'''<p style="text-align: center">These QBasic keywords (with a few noted exceptions) will work in all versions of QB64.</p>''' <div id = "A">A</div> * [[ABS]] (function) {{text|converts any negative numerical value to a positive value.}} @@ -403,7 +413,6 @@ __NOTOC__ * [[ALIAS]] (QB64 [[DECLARE LIBRARY]] statement) {{text|denotes the actual name of an imported [[FUNCTION]] or [[SUB]] procedure.}} * [[AND]] (logical operator) {{text|is used to compare two numerical values bitwise.}} * [[AND (boolean)]] {{text| conditonal operator is used to include another evaluation in an [[IF...THEN]] or [[Boolean]] statement.}} -* [[ANY]] (variable type) {{text|disables type checking for a variable used in a [[SUB]] or [[FUNCTION]] declaration.}} * [[APPEND]] (file mode) {{text|creates a new file or allows an existing file to have data added using [[WRITE (file statement)|WRITE]] or [[PRINT (file statement)|PRINT]]}} * [[AS]] {{text|is used to denote a variable type or file number.}} * [[ASC]] (function) {{text|returns the [[ASCII]] code number of a text [[STRING|string]] character.}} @@ -445,7 +454,7 @@ __NOTOC__ * [[CLOSE]] (statement) {{text|closes specific file number(s) or all files when a number is not specified.}} * [[CLS]] (statement) {{text|clears a program [[SCREEN|screen]], [[VIEW]] port or [[WINDOW]].}} * [[COLOR]] (statement) {{text|sets the current text foreground and/or background color to be used.}} -* [[COMMAND$]] (function) {{text|returns the [[DOS]] commandline arguments passed when a program is run.}} +* [[COMMAND$]] (function) {{text|returns the command line arguments passed when a program is run.}} * [[COMMON]] (statement) {{text|sets a variable name as shared by [[CHAIN]]ed program modules.}} * [[CONST]] (statement) {{text|sets a variable name and its value as a constant value to be used by all procedures.}} * [[COS]] (function) {{text|returns the cosine of a radian angle value.}} @@ -468,7 +477,7 @@ __NOTOC__ * [[DATE$]] (function) {{text|returns the present Operating System date [[STRING|string]] formatted as mm-dd-yyyy.}} * [[DATE$ (statement)]] {{text|sets the date of the Operating System using a mm-dd-yyyy [[STRING|string]] format.}} * [[DECLARE]] (BASIC statement) {{text|declares a [[SUB]] or [[FUNCTION]] procedure at the start of a program. Not required in QB64.}} -* [[DECLARE (non-BASIC statement)]] {{text|declares non-basic [[SUB]] or [[FUNCTION]] procedures. NOT IMPLEMENTED!}} +* [[DECLARE (non-BASIC statement)]] {{text|declares non-basic [[SUB]] or [[FUNCTION]] procedures. Not implemented in QB64.}} * [[DECLARE LIBRARY|DECLARE LIBRARY (QB64 statement block)]] {{text|declares a C++, SDL or Operating System [[SUB]] or [[FUNCTION]] to be used.}} * [[DECLARE DYNAMIC LIBRARY|DECLARE DYNAMIC LIBRARY (QB64 statement)]] {{text|declares DYNAMIC, CUSTOMTYPE or STATIC library(DLL) [[SUB]] or [[FUNCTION]].}} * [[DEF FN]] (statement) {{text|defines a function procedure in the main program that cannot be used recursively.}} @@ -479,7 +488,6 @@ __NOTOC__ * [[DEFSNG]] (statement) {{text|defines a set of undefined variable name starting letters as [[SINGLE]] type numerical values.}} * [[DEFSTR]] (statement) {{text|defines a set of undefined variable name starting letters as [[STRING]] type values.}} * [[DIM]] (statement) {{text|defines a variable as a specified type and can size a [[STATIC]] array.}} -* [[DIR$]] (PDS function) {{text|derived function code used to find a list of files by name. '''NOT A QB64 FUNCTION'''}} * [[DO...LOOP]] (statement) {{text|sets a recursive procedure loop that can be ignored or exited using conditional arguments.}} * [[DOUBLE]] (numerical type #) {{text|8 byte value limited to values up to 15 decimal places.}} * [[DRAW]] (statement) {{text|uses a special [[STRING|string]] format that draws graphical lines in specific directions.}} @@ -521,7 +529,7 @@ __NOTOC__ * [[FOR...NEXT]] (statement) {{text|creates a recursive loop procedure that loop a specified number of times.}} * [[FOR (file statement)]] {{text|used in an [[OPEN]] file or device statement to indicate the access mode.}} * [[FRE]] (function) {{text|returns the number of bytes of Memory available to running programs.}} -* [[TIMER (statement)|FREE (QB64 TIMER statement)]] {{text|frees a numbered TIMER event in QB64 only.}} +* [[TIMER (statement)|FREE (QB64 TIMER statement)]] {{text|frees a numbered TIMER event in QB64.}} * [[FREEFILE]] (file function) {{text|returns a file number that is currently not in use by the Operating System.}} * [[FUNCTION]] (procedure block) {{text|sub-procedure that can calculate and return one value to a program in its name.}} @@ -589,16 +597,16 @@ __NOTOC__ * [[LCASE$]] (function) {{text|returns the lower case value of a [[STRING]].}} * [[LEFT$]] (function) {{text|returns the specified number of text characters from the left end of a [[STRING]].}} * [[LEN]] (function) {{text|returns the length or number of characters in a [[STRING]] value in bytes.}} -* [[LET]] (statement) {{text|assigns a variable a literal value. Not required!}} +* [[LET]] (statement) {{text|assigns a variable a literal value. Not required.}} * [[LINE]] (statement) {{text|creates a graphic line or box on the [[SCREEN]].}} * [[LINE INPUT]] (statement) {{text|user input can be any text character including commas and quotes as a [[STRING]] value only.}} * [[LINE INPUT (file statement)]] {{text|returns an entire text file line and returns it as a [[STRING]] value.}} -* [[KEY LIST|LIST]] {{text|displays the current [[ON KEY(n)]] function key(F1 to F10) "soft key" settings.}} +* [[KEY LIST|LIST]] {{text|displays the current [[ON KEY(n)]] function key (F1 to F10) "soft key" settings.}} * [[LOC]] (function) {{text|returns the present file byte position or number of bytes in the [[OPEN COM]] buffer.}} * [[LOCATE]] (statement) {{text|sets the text cursor's row and column position for a [[PRINT]] or [[INPUT]] statement.}} * [[LOCK]] (statement) {{text|restricts access to portions or all of a file by other programs or processes.}} * [[LOF]] (function) {{text|returns the size of an [[OPEN]] file in bytes.}} -* [[LOG]] (function) {{text| +* [[LOG]] (function) {{text|returns the natural logarithm of a specified numerical value}} * [[LONG]] (& numerical type) {{text|4 byte whole values from -2147483648 to 2147483647.}} * [[DO...LOOP|LOOP]] (block statement) {{text|bottom end of a recursive DO loop.}} * [[LPOS]] (function) {{text|returns the printer head position.}} @@ -639,7 +647,7 @@ __NOTOC__ <div id = "O">O</div> -* [[OCT$]] (function) {{text|returns the octal(base 8) [[STRING]] representation of a decimal [[INTEGER]] value.}} +* [[OCT$]] (function) {{text|returns the octal (base 8) [[STRING]] representation of a decimal [[INTEGER]] value.}} * [[OFF]] (event statement) {{text|turns off all [[ON]] event checking.}} * [[ON COM(n)]] (statement) {{text|sets up a COM port event procedure call.}} * [[ON ERROR]] (statement) {{text|sets up and activates an error event checking procedure call. Use to avoid program errors.}} @@ -648,7 +656,7 @@ __NOTOC__ * [[ON PLAY(n)]] (statement) {{text|sets up a [[PLAY]] event procedure call.}} * [[ON STRIG(n)]] (statement) {{text|sets up a joystick button event procedure call.}} * [[ON TIMER(n)]] (statement) {{text|sets up a timed event procedure call.}} -* [[ON UEVENT]] (statement) '''{{text|Currently NOT supported in QB64!}}''' +* [[ON UEVENT]] (statement) '''{{text|Not implemented in QB64.}}''' * [[ON...GOSUB]] (statement) {{text|sets up a numberical event procedure call.}} * [[ON...GOTO]] (statement) {{text|sets up a numberical event procedure call.}} * [[OPEN]] (file statement) {{text|opens a file name for an access mode with a specific file number.}} @@ -727,8 +735,8 @@ __NOTOC__ * [[SETMEM]] (function) {{text|sets the memory to use.}} * [[SGN]] (function) {{text|returns -1 for negative, 0 for zero, and 1 for positive numerical values.}} * [[SHARED]] (statement) {{text|designates that a variable can be used by other procedures or the main procedure when in a sub-procedure.}} -* [[SHELL]] (statement) {{text|sends [[STRING]] commands to the [[DOS]] command line. SHELL calls will not affect the current path.}} -* [[SHELL (function)|SHELL (QB64 function)]] {{text|executes a [[DOS]] command or calls another program. Returns codes sent by [[END]] or [[SYSTEM]].}} +* [[SHELL]] (statement) {{text|sends [[STRING]] commands to the command line. SHELL calls will not affect the current path.}} +* [[SHELL (function)|SHELL (QB64 function)]] {{text|executes an external command or calls another program. Returns codes sent by [[END]] or [[SYSTEM]].}} * [[SIGNAL]] (OS 2 event) * [[SIN]] (function) {{text|returns the sine of a [[radians|radian]] angle.}} * [[SINGLE]] (! numerical type) {{text|4 byte floating decimal point values up to 7 decimal places.}} @@ -776,7 +784,7 @@ __NOTOC__ <div id = "U">U</div> * [[UBOUND]] (function) {{text|returns the upper-most index number of a designated [[arrays|array]].}} * [[UCASE$]] (function) {{text|returns an uppercase representation of a specified [[STRING]].}} -* [[UEVENT]] (statement) '''{{text|Currently NOT supported in QB64!}}''' +* [[UEVENT]] (statement) '''{{text|Not implemented in QB64.}}''' * [[UNLOCK]] (statement) {{text|unlocks a designated file or portions of it.}} * [[UNTIL]] (condition) {{text|evaluates a [[DO...LOOP]] condition until it is True.}} @@ -825,8 +833,8 @@ __NOTOC__ --> ==OpenGL specific keywords:== -<center>'''All QB64 GL keywords must use the underscore _gl prefix with the alphabetically listed function names.'''</center> -<center>'''The following keywords cannot be used in QB64 SDL versions .954 and below!'''</center> +<center>'''All QB64 OpenGL keywords must use the underscore _gl prefix with the alphabetically listed function names.'''</center> +<center>'''The following keywords cannot be used in QB64 versions .954 and below.'''</center> <div id = "glA">_glA</div> @@ -1134,6 +1142,7 @@ __NOTOC__ * [[_glRectiv]] (statement) {{text|OpenGL command}} * [[_glRects]] (statement) {{text|OpenGL command}} * [[_glRectsv]] (statement) {{text|OpenGL command}} +* [[_GLRENDER]] (statement) {{text|sets whether context is displayed, on top of or behind the software rendering.}} * [[_glRenderMode]] (statement) {{text|OpenGL command}} * [[_glRotated]] (statement) {{text|OpenGL command}} * [[_glRotatef]] (statement) {{text|OpenGL command}} @@ -1248,11 +1257,11 @@ __NOTOC__ ==Symbols:== <center>'''QB64 and QB Symbols:'''</center> -<center>''[Note: All symbols below can also be used inside of literal quoted strings except for quotation marks!]''</center> +<center>''[Note: All symbols below can also be used inside of literal quoted strings except for quotation marks.]''</center> :'''Print, Input or File Formatting''' -* [[Semicolon|; Semicolon]] after a [[PRINT]] stops invisible cursor at end of printed value. Can prevent screen rolling! A [[Semicolon]] after the [[INPUT]] prompt text will display a question mark after the text. +* [[Semicolon|; Semicolon]] after a [[PRINT]] stops invisible cursor at end of printed value. Can prevent screen rolling. A [[Semicolon]] after the [[INPUT]] prompt text will display a question mark after the text. * [[Comma|, Comma]] after a [[PRINT]] tabs invisible cursor past end of printed value. After the [[INPUT]] prompt text a [[comma]] displays no [[Question mark]]. * [[Quotation mark|" Quotation mark]] delimits the ends of a literal [[STRING]] value in a [[PRINT]], [[INPUT]] or [[LINE INPUT]] statement. * [[Question mark|? Question mark]] is a shortcut substitute for the [[PRINT]] keyword. Will change to PRINT when cursor leaves the code line. @@ -1262,11 +1271,11 @@ __NOTOC__ * [[Apostrophe|' Apostrophe]] ignores a line of code or program comment and MUST be used before a [[Metacommand]]. Same as using [[REM]]. * [[Comma|, Comma]] is used to separate [[DATA]], [[SUB]] or [[FUNCTION]] parameter variables. * [[Colon|: Colon]]s can be used to separate two procedure statements on one code line. -* [[Dollar_Sign|$ Dollar sign]] prefix denotes a Qbasic [[Metacommand]]. '''QB64''''s event [[$CHECKING]] is NOT commented. +* [[Dollar_Sign|$ Dollar sign]] prefix denotes a QBasic [[Metacommand]]. * [[Parenthesis|( ) Parenthesis]] enclose a math or conditional procedure order, [[SUB]] or [[FUNCTION]] parameters or to pass by value. * [[+|+ Plus]] [[concatenation]] operator MUST be used to combine literal string values in a variable definition. * [[Quotation mark|" Quotation mark]] designates the ends of a literal [[STRING]] value. Use [[CHR$]](34) to insert quotes in a text [[STRING]]. -* [[Underscore|_ Underscore]] can be used to continue a line of code to the next program line in '''QB64 only'''. +* [[Underscore|_ Underscore]] can be used to continue a line of code to the next program line in '''QB64'''. <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> :'''Variable Name Type Suffixes''' @@ -1278,7 +1287,7 @@ __NOTOC__ * [[INTEGER|% INTEGER]] [[INTEGER|whole]] numerical type (2 bytes) * [[LONG|& LONG]] [[INTEGER|whole]] numerical type (4 bytes} * [[_INTEGER64|&& _INTEGER64]] '''QB64''' [[INTEGER|whole]] numerical type (8 bytes) -* [[_BIT|` _BIT]] '''QB64''' [[INTEGER|whole]] numerical type (1 bit)(Key below tilde(~) or [[CHR$]](96)) +* [[_BIT|` _BIT]] '''QB64''' [[INTEGER|whole]] numerical type (1 bit) (Key below tilde (~) or [[CHR$]](96)) * [[_BYTE|%% _BYTE]] '''QB64''' [[INTEGER|whole]] numerical type (1 byte) * [[_OFFSET|%& _OFFSET]] '''QB64''' [[INTEGER|whole]] numerical pointer address type (any byte size required) @@ -1335,15 +1344,15 @@ __NOTOC__ [http://www.qb64.net/forum/index.php Visit QB64 Community Forum] -'''Links to other Qbasic Sites:''' +'''Links to other QBasic Sites:''' -[http://qbasicstation.com/index.php?c=p_member Member programs at Qbasic Station] +[http://qbasicstation.com/index.php?c=p_member Member programs at QBasic Station] -[http://www.network54.com/Index/10167 Qbasic Forum at Network 54] +[http://www.network54.com/Index/10167 QBasic Forum at Network 54] -[http://www.petesqbsite.com/forum/ Pete's Qbasic Forum] +[http://www.petesqbsite.com/forum/ Pete's QBasic Forum] -[http://www.petesqbsite.com/downloads/downloads.shtml Pete's Qbasic Downloads]</center> +[http://www.petesqbsite.com/downloads/downloads.shtml Pete's QBasic Downloads]</center> <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> \ No newline at end of file diff --git a/internal/help/Keyword_Reference_-_By_usage.txt b/internal/help/Keyword_Reference_-_By_usage.txt index 370851ce3..9489a6711 100644 --- a/internal/help/Keyword_Reference_-_By_usage.txt +++ b/internal/help/Keyword_Reference_-_By_usage.txt @@ -25,11 +25,6 @@ :::: Offline WIKI Reference contributed by OlDosLover -:If '''FIREFOX browser''' does not copy page example code correctly use another browser or: - -::::Download page: [[Mozilla FireFox Code Copy Add On]] - - :'''If code examples only display partial code, use the browser Refresh button!''' @@ -86,6 +81,8 @@ * [[_BACKGROUNDCOLOR]] (function) {{text|returns the current background color.}} * [[_BLEND]] (statement) {{text|turns on alpha blending for the current image or a specific one.}} * [[_BLEND (function)]] {{text|returns if blending is enabled or disabled for the current window or a specified image handle.}} +* [[_BLINK]] (statement) {{text|statement turns blinking colors on/off in SCREEN 0}} +* [[_BLINK (function)]] {{text|returns -1 if enabled or 0 if disabled by [[_BLINK]] statement.}} * [[_BLUE]] (function) {{text|returns the palette intensity OR the blue component intensity of a 32-bit image color.}} * [[_BLUE32]] (function) {{text|returns the blue component intensity of a 32-bit image color.}} * [[_CLEARCOLOR]] (statement) {{text|sets a specific color to be treated as transparent in an image}} @@ -876,9 +873,10 @@ The following table describes the error codes that are reported by the '''QB64'' <p style="text-align: center">([[#toc|Return to Table of Contents]])</p> == Program Flow and Loops: == +* [[_CONTINUE]] (statement) {{text|skips the remaining lines in a control block (DO/LOOP, FOR/NEXT or WHILE/WEND)}} * [[_DEST]] (statement) {{text|sets the current write image or page. All graphics will go to this image.}} * [[_DEST (function)]] {{text|returns the current write destination image or page.}} -*[[_EXIT (function)]] {{text|prevents a user exit and indicates if a user has clicked the close X window button or CTRL + BREAK.}} +* [[_EXIT (function)]] {{text|prevents a user exit and indicates if a user has clicked the close X window button or CTRL + BREAK.}} * [[_SOURCE]] (statement) {{text|establishes the image SOURCE using a designated image handle}} * [[_SOURCE (function)]] {{text|returns the present image _SOURCE handle value.}} * [[_SHELLHIDE]] (function) {{text|returns the code sent by a program exit using [[END]] or [[SYSTEM]] followed by an [[INTEGER]] value.}} @@ -918,7 +916,7 @@ The following table describes the error codes that are reported by the '''QB64'' == Sounds and Music using Sound Card: == -* [[_SNDBAL]] (statement) {{text|attempts to set the balance or 3D position of a sound.}} +* [[_SNDBAL]] (statement) {{text|sets the balance or 3D position of a sound.}} * [[_SNDCLOSE]] (statement) {{text|frees and unloads an open sound using a _SNDOPEN or _SNDCOPY handle.}} * [[_SNDCOPY]] (function) {{text|copies a sound to a new handle so that two or more of the same sound can be played at once.}} * [[_SNDGETPOS]] (function) {{text|returns the current playing position in seconds of a designated sound handle.}} @@ -930,7 +928,7 @@ The following table describes the error codes that are reported by the '''QB64'' * [[_SNDPAUSED]] (function) {{text|returns the pause status of a specified sound handle.}} * [[_SNDPLAY]] (statement) {{text|plays a designated sound file handle.}} * [[_SNDPLAYCOPY]] (statement) {{text|copies a sound, plays it and automatically closes the copy using a handle parameter}} -* [[_SNDPLAYFILE]] (statement) {{text|a simple command to play a sound file with limited options for SYNC and volume.}} +* [[_SNDPLAYFILE]] (statement) {{text|a simple command to play a sound file with limited options.}} * [[_SNDPLAYING]] (function) {{text|returns whether a sound handle is being played.}} * [[_SNDRATE]] (function) {{text|returns the sample rate frequency per second of the current computer's sound card.}} * [[_SNDRAW]] (statement) {{text|plays sound wave sample frequencies created by a program.}} diff --git a/internal/help/LBOUND.txt b/internal/help/LBOUND.txt index f8ca1f778..552643453 100644 --- a/internal/help/LBOUND.txt +++ b/internal/help/LBOUND.txt @@ -1,18 +1,16 @@ -The {{KW|LBOUND}} function returns the smallest valid index (lower bound) of an array dimension. +The [[LBOUND]] function returns the smallest valid index (lower bound) of an array dimension. {{PageSyntax}} -:''result%'' = {{KW|LBOUND}}({{Parameter|arrayName}}[, {{Parameter|dimension%}}]) +:{{Parameter|result%}} = [[LBOUND]]({{Parameter|arrayName}}[, {{Parameter|dimension%}}]) {{PageDescription}} * {{Parameter|arrayName}} specifies the name of the array. - * {{Parameter|dimension%}} specifies the dimension number, starting with <code>1</code> for the first dimension. ** If omitted, {{Parameter|dimension%}} is assumed to be <code>1</code>. ** If {{Parameter|dimension%}} is less than <code>1</code> or is greater than the number of dimensions, a [[ERROR Codes|subscript out of range]] error occurs. - -* {{KW|LBOUND}}, along with {{KW|UBOUND}}, is used to determine the range of valid indexes of an array. +* [[LBOUND]] and [[UBOUND]] are used to determine the range of valid indexes of an array. {{PageExamples}} @@ -28,8 +26,8 @@ The {{KW|LBOUND}} function returns the smallest valid index (lower bound) of an {{PageSeeAlso}} -* {{KW|Arrays}}, {{KW|UBOUND}} -* {{KW|DIM}}, {{KW|COMMON}}, {{KW|STATIC}}, {{KW|SHARED}} +* [[Arrays]], [[UBOUND]] +* [[DIM]], [[COMMON]], [[STATIC]], [[SHARED]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LCASE$.txt b/internal/help/LCASE$.txt index 3361927c0..bde05a74a 100644 --- a/internal/help/LCASE$.txt +++ b/internal/help/LCASE$.txt @@ -1,15 +1,16 @@ -The '''LCASE$''' function changes the uppercase letters of a {{KW|STRING}} to lowercase. +The [[LCASE$]] function outputs an all-lowercase version of a [[STRING]]. {{PageSyntax}} -:''result$'' = '''LCASE$('''{{Parameter|text$}}''')''' +:{{Parameter|result$}} = [[LCASE$]]({{Parameter|text$}}) {{PageDescription}} * Normally used to guarantee that user input is not capitalized. -* Will not affect non alphabet string characters. +* Does not affect non-alphabetical characters. +{{PageExamples}} ''Example:'' The following code guarantees that all user letter entries will be lower case: {{CodeStart}}{{Cl|PRINT}} "Do you want to continue? (y/n)" diff --git a/internal/help/LEFT$.txt b/internal/help/LEFT$.txt index bcc31fa02..458d12ebc 100644 --- a/internal/help/LEFT$.txt +++ b/internal/help/LEFT$.txt @@ -1,22 +1,22 @@ -The '''LEFT$''' string function returns a part of a [[STRING]] from the start a set number of places. - +The [[LEFT$]] string function returns a number of characters from the left of a [[STRING]]. {{PageSyntax}} -:: '''LEFT$('''''stringvalue$'', ''numberofcharacters%''''')''' +: [[LEFT$]]({{Parameter|stringValue$}}, {{Parameter|numberOfCharacters%}}) {{Parameters}} -* The ''stringvalue$'' can be any [[STRING]] variable of [[ASCII]] text characters. -* The ''numberofcharacters'' [[INTEGER]] value determines the number of characters to return from left end of string. +* {{Parameter|stringValue$}} can be any [[STRING]] literal or variable. +* {{Parameter|numberOfCharacters%}} [[INTEGER]] determines the number of characters to return from left of string. {{PageDescription}} -* If the number of characters exceeds the string length the entire string is returned. Use [[LEN]] to determine a string length. -* LEFT$ returns always start at the first character of the string, even when a space. [[LTRIM$]] can remove leading spaces. -* '''The Number of characters cannot be a negative value.''' +* If the number of characters exceeds the string length the entire string is returned. Use [[LEN]] to determine a string's length. +* [[LEFT$]] returns always start at the first character of the string, even if it's a space. [[LTRIM$]] can remove leading spaces. +* '''{{Parameter|numberOfCharacters%}} cannot be a negative value.''' +{{PageExamples}} ''Example 1:'' Getting the left portion of a string value. {{CodeStart}} '' '' name$ = "Tom Williams" @@ -28,7 +28,7 @@ PRINT First$ '' '' {{OutputStart}}Tom {{OutputEnd}} -''Example 2:'' A Replace function using LEFT$ and [[RIGHT$]] with [[INSTR]] to insert a different length word into an existing string. +''Example 2:'' A replace function using LEFT$ and [[RIGHT$]] with [[INSTR]] to insert a different length word into an existing string. {{CodeStart}} '' '' text$ = "This is my sentence to change my words." {{Cl|PRINT}} text$ @@ -59,7 +59,7 @@ This is your sentence to change your words.{{OutputEnd}} : ''Note:'' The [[MID$ (statement)|MID$]] statement can only substitute words or sections of the original string length. It cannot change the string length. -''See also:'' +{{PageSeeAlso}} * [[RIGHT$]], [[MID$]] * [[LTRIM$]], [[RTRIM$]] * [[MID$ (statement)]] diff --git a/internal/help/LEN.txt b/internal/help/LEN.txt index 6d9e3a043..846e7fc7d 100644 --- a/internal/help/LEN.txt +++ b/internal/help/LEN.txt @@ -1,27 +1,28 @@ -The '''LEN''' function returns the number of bytes used by a variable value and the number of characters in a [[STRING]]. +The [[LEN]] function returns the number of bytes used by a variable value and the number of characters in a [[STRING]]. {{PageSyntax}} -:: length% = LEN(variable$) +: {{Parameter|length%}} = [[LEN]]({{Parameter|literalTextOrVariable}}) * Literal or variable [[STRING]] values return the number of string bytes which is the same as the number of string characters. * A numerical ''variable'' will return the number of bytes used by a numerical variable type. -** [[_BIT]] variable types and bit multiples '''cannot be measured in bytes'''. ** [[_BYTE]] variable types return 1 byte. ** [[INTEGER]] variable types return 2 bytes. -** [[SINGLE]] and [[LONG]] Integer variable types return 4 bytes. +** [[SINGLE]] and [[LONG]] integer variable types return 4 bytes. ** [[DOUBLE]] and [[_INTEGER64]] variable types return 8 bytes. ** [[_FLOAT]] variable types return 32 bytes. ** [[_OFFSET]] and [[_MEM]] variable types return varying byte sizes. -* '''LEN cannot return lengths of literal numerical values and will create a "variable required" status error in the [[IDE]]!''' +** ''Note:'' [[_BIT]] variable types and bit multiples '''cannot be measured in bytes'''. +* '''LEN cannot return lengths of literal numerical values and will create a "variable required" status error in the [[IDE]].''' * '''LEN =''' can be used with a user defined [[TYPE]] variable to determine the number of bytes used in [[RANDOM]] file records: -:::: '''{{text|[[OPEN]] file$ FOR [[RANDOM]] AS #n LEN <nowiki>=</nowiki> LEN(record_type_variable)|green}}''' -* If a LEN = statement is not used, [[RANDOM]] default record length is 128 or sequencial is 512 up to a maximum of 32767 bytes. -* [[BINARY]] OPEN statements will ignore LEN = statements. The byte size of a [[GET|read]] or [[PUT|write]] is determined by the [[Variable Types|variable type]]. +:::: {{InlineCode}}[[OPEN]] file$ FOR [[RANDOM]] AS #n LEN <nowiki>=</nowiki> LEN(recordTypeVariable){{InlineCodeEnd}}''' +:* If a LEN = statement is not used, [[RANDOM]] default record length is 128 or sequencial is 512 up to a maximum of 32767 bytes. +:* [[BINARY]] OPEN statements will ignore LEN = statements. The byte size of a [[GET|read]] or [[PUT|write]] is determined by the [[Variable Types|variable type]]. +{{PageExamples}} ''Example 1:'' With a string variable the byte size is the same as the number of characters. {{CodeStart}} LastName$ = "Williams" @@ -109,7 +110,7 @@ PRINT NumRecords%; "records" : To read the last record [[GET]] the number of records. To add a record, use the number of records + 1 to [[PUT]] new record data. -''See also:'' +{{PageSeeAlso}} * [[LOF]], [[EOF]] * [[AS]], [[TYPE]] * [[RANDOM]], [[BINARY]] diff --git a/internal/help/LET.txt b/internal/help/LET.txt index 3bfd47840..e32bc1f71 100644 --- a/internal/help/LET.txt +++ b/internal/help/LET.txt @@ -1,18 +1,20 @@ -The '''LET''' is a useless statement designed by [[cavemen]] when they started programming. +The [[LET]] is a useless statement designed by [[cavemen]] when they started programming. {{PageSyntax}} -:: [LET] variable = expression +: '''[LET]''' {{Parameter|variable}} = {{Parameter|expression}} -* LET a = 12 is the same as a = 12 but wastes 4 extra bytes of program space. +{{PageDescription}} +* {{InlineCode}}LET a = 12{{InlineCodeEnd}} is the same as {{InlineCode}}a = 12{{InlineCodeEnd}}, but wastes 4 extra bytes of program space. * Teachers should be SHOT for even teaching about it! Move on! -''Notes:'' LET is '''optional''', its the only keyword where the '''entire keyword''' is optional :) +''Notes:'' LET is '''optional''', it's the only keyword where the '''entire keyword''' is optional :-) -''See also:'' +{{PageSeeAlso}} * [[Cavemen]] +* [[Variable]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LINE.txt b/internal/help/LINE.txt index 248e10dbb..7b42db045 100644 --- a/internal/help/LINE.txt +++ b/internal/help/LINE.txt @@ -1,32 +1,32 @@ -The '''LINE''' statement is used in graphics [[SCREEN (statement)|SCREEN]] modes to create lines or boxes. - +The [[LINE]] statement is used in graphic [[SCREEN (statement)|SCREEN]] modes to create lines or boxes. {{PageSyntax}} -: '''LINE''' [STEP] [(''column1'', ''row1'')]'''-'''[STEP] '''('''''column2'', ''row2'''''),''' ''color''[, [{B|BF}], style%] +: [[LINE]] [STEP] ['''('''''column1''''',''' ''row1''''')''']'''-'''[STEP] '''('''''column2'', ''row2'''''),''' ''color''[, [{B|BF}], {{Parameter|style%}}] {{Parameters}} -* Can use [[STEP]] keyword for graphics coordinates relative to the previously placed object before either set of coordinates. -* The optional parameters (''column1'', ''row1'') set the first coordinate or use the last previous object coordinate when omitted. +* The [[STEP]] keyword make ''column'' and ''row'' coordinates relative to the previously coordinates set by any graphic statement. +* The optional parameters (''column1'', ''row1'') set the line's starting point. * The dash and second coordinate parameters (''column2'', ''row2'') must be designated to complete the line or box. -* The [[INTEGER]] ''color'' attribute or [[LONG]] [[_RGB32]] 32 bit color value sets the line, box or full box color. -* Optional '''B''' creates a box outline using the start and end coordinates as diagonal corners. '''BF''' creates a filled box. -* The ''style'' [[INTEGER]] value sets dashed lines with varying patterns when using values from 0 to 32767. +* The [[INTEGER]] ''color'' attribute or [[LONG]] [[_RGB32]] 32 bit color value sets the drawing color. If omitted, the current [[_DEST|destination]] page's [[_DEFAULTCOLOR]] is used. +* Optional '''B''' keyword creates a rectangle ('''b'''ox) using the start and end coordinates as diagonal corners. '''BF''' creates a '''b'''ox '''f'''illed. +* The ''style%'' signed [[INTEGER]] value sets a dotted pattern to draw the line or rectangle outline. {{PageDescription}} -* Creates a colored line from coordinate1 to coordinate2 if the box options(B or BF) are omitted. Can be drawn partially offscreen. -* '''B''' creates a box outline with each side parallel to the program screen sides. '''BF''' creates an identical filled box. -* '''B''' can be used with style to create a dash pattern on all 4 box sides. '''BF cannot be used with style.''' -* Both commas are required with style even when not creating a box. The lines are created where the style determines. -* The QB64 and QB graphic cursor is set to the center of the program window on program start. -* '''LINE can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only!''' +* Creates a colored line between the given coordinates. Can be drawn partially off screen. +* '''B''' creates a box outline with each side parallel to the program screen sides. '''BF''' creates a filled box. +* {{Parameter|style%}} can be used to create a dotted pattern to draw the line. +** '''B''' can be used with a ''style%'' to draw the rectangle outline using the desired pattern. +** '''BF''' ignores the {{Parameter|style%}} parameter. See examples 2, 3 and 4 below. +* The graphic cursor is set to the center of the program window on program start. Using the [[STEP]] keyword makes the coordinates relative to the current graphic cursor. +* [[LINE]] '''can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only.''' +{{PageExamples}} ''Example 1:'' Following one line with another by omitting the second line's first coordinate parameter bracket entirely: -{{CodeStart}} '' '' -{{Cl|SCREEN}} 12 +{{CodeStart}}{{Cl|SCREEN}} 12 {{Cl|LINE}} (100, 100)-(200, 200), 10 'creates a line {{Cl|LINE}} -(400, 200), 12 'creates a second line from end of first @@ -37,8 +37,7 @@ The '''LINE''' statement is used in graphics [[SCREEN (statement)|SCREEN]] modes ''Example 2:'' Creating styled lines and boxes with the LINE statement. Different style values create different dashed line spacing. -{{CodeStart}} '' '' -{{Cl|SCREEN}} 12 +{{CodeStart}}{{Cl|SCREEN}} 12 {{Cl|LINE}} (100, 100)-(300, 300), 10, , 63 'creates a styled line {{Cl|LINE}} (100, 100)-(300, 300), 12, B, 255 'creates styled box shape @@ -48,10 +47,42 @@ The '''LINE''' statement is used in graphics [[SCREEN (statement)|SCREEN]] modes :''Explanation:'' The first diagonal dashed green line bisects the red dashed square from Top Left to Bottom Right Corners. -''See also:'' +''Example 3:'' The ''style'' value sets each 16 pixel line section as the value's bits are set on or off: +{{CodeStart}}{{Cl|SCREEN}} 13 +{{Cl|_FULLSCREEN}} 'required in QB64 only +{{Cl|_DELAY}} 5 +{{Cl|FOR...NEXT|FOR}} i% = 1 {{Cl|TO}} 2 ^ 15 'use exponential value instead of -32768 + {{Cl|COLOR}} 15:{{Cl|LOCATE}} 10, 5: {{Cl|PRINT}} i%; + {{Cl|LINE}} (10, 60)-(300, 60), 0 'erase previous lines + {{Cl|LINE}} (10, 60)-(300, 60), 12, , i% + tmp$ = "" + {{Cl|FOR...NEXT|FOR}} b% = 15 {{Cl|TO}} 0 {{Cl|STEP}} -1 'create binary text value showing bits on as {{text|█|red}}, off as space + {{Cl|IF...THEN|IF}} i% {{Cl|AND}} 2 ^ b% {{Cl|THEN}} tmp$ = tmp$ + {{Cl|CHR$}}(219) {{Cl|ELSE}} tmp$ = tmp$ + {{Cl|SPACE$}}(1) + {{Cl|NEXT}} + {{Cl|COLOR}} 12:{{Cl|LOCATE}} 10, 20: {{Cl|PRINT}} tmp$; + {{Cl|IF...THEN|IF}} {{Cl|INKEY$}} <> "" {{Cl|THEN}} {{Cl|EXIT}} {{Cl|FOR...NEXT|FOR}} 'any key exit + {{Cl|_DELAY}} .001 'set delay time as required +{{Cl|NEXT}} '' '' +{{CodeEnd}} +: ''Explanation:'' The ''style'' value's Most Significant Bit (MSB) is set to the left with LSB on right as 16 text blocks are set on or off. + + +''Example 4:'' Using [[&B|binary code]] to design a style pattern: +{{CodeStart}}{{Cl|SCREEN}} 12 + +{{Cl|LINE}} (100, 100)-(300, 100), 10, , &B0000111100001111 '16-bits +{{Cl|LINE}} (100, 110)-(300, 110), 11, , &B0011001100110011 +{{Cl|LINE}} (100, 120)-(300, 120), 12, , &B0101010101010101 +{{Cl|LINE}} (100, 130)-(300, 130), 13, , &B1000100010001000 +{{CodeEnd}} +:''Explanation:'' The binary pattern created with 0s and 1s using the [[&B]] number prefix define the pattern to draw the colored lines. + + +{{PageSeeAlso}} * [[SCREEN (statement)|SCREEN]], [[COLOR]] * [[DRAW]], [[CIRCLE]], [[STEP]] * [[PSET]], [[PRESET]] +* [[AND]], [[OR]] {{text|(logical operators)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LINE_INPUT.txt b/internal/help/LINE_INPUT.txt index d63494ae6..90108ca99 100644 --- a/internal/help/LINE_INPUT.txt +++ b/internal/help/LINE_INPUT.txt @@ -1,30 +1,28 @@ -The '''LINE INPUT''' statement requests a [[STRING]] keyboard entry from a program user. - +The [[LINE INPUT]] statement requests a [[STRING]] keyboard entry from a program user. {{PageSyntax}} -:: '''LINE INPUT''' [;] '''"'''[text prompt or question]'''"{,|;} string_variable$''' -:: '''LINE INPUT ; string_variable$''' +: [[LINE INPUT]] [;] "[text prompt or question]"{,|;} {{Parameter|stringVariable$}} +: [[LINE INPUT]] ; {{Parameter|stringVariable$}} -''[[Parameters]]:'' -* [[semicolon]] after LINE INPUT stops the cursor after the entry and prevents screen roll on lowest two screen rows. -* ''text statement or question'' is optional, but quotes are necessary unless just a semicolon is used before the ''variable''. -* [[comma]] separator for a statement or [[semicolon]] for a question mark following the text. -* No text with a semicolon displays a question mark with a space and keeps the cursor after the entry. -* Requires ONE [[STRING|string]] variable to hold the entire text entry. +{{Parameters}} +* A [[semicolon]] immediately after LINE INPUT stops the cursor after the entry and prevents screen roll on the lowest two screen rows. +* ''text prompt or question'' is optional, but quotes are necessary unless just a semicolon is used before the {{Parameter|stringVariable$}}. +* Requires only one [[STRING|string]] variable to hold the entire text entry. -''Usage:'' -* Cannot use numerical [[type]] variables or [[comma]] separated variable lists for multiple entries! +{{PageDescription}} +* Cannot use numerical [[type]] variables or [[comma]] separated variable lists for multiple entries. * Allows [[comma]]s and [[quotation mark]]s in the user input, unlike [[INPUT]] where commas denote extra input values and quotes delimit strings. -* The statement stops the procedure until an entry is made. Pressing Enter ends the entry and code execution resumes. +* The statement halts the program until an entry is made. Pressing Enter ends the entry and code execution resumes. * LINE INPUT does not trim off leading or trailing spaces in the string entry like [[INPUT]] string returns. -* Use [[VAL]] to convert string numbers and [[&O]](octal) or [[&H]](hexadecimal) prefixed entries into numerical values. -* Use [[_DEST]] [[_CONSOLE]] before LINE INPUT statements to be used in a [[$CONSOLE|console]] window. -* '''Note: QB64''' will NOT remove CHR$(0) from the end of LINE INPUT string return values like Qbasic did. +* Use [[VAL]] to convert string numbers and [[&O]] (octal), [[&H]] (hexadecimal) or [[&B]] (binary) prefixed entries into numerical values. +* Use [[_DEST]] [[_CONSOLE]] before LINE INPUT statements to receive input from a [[$CONSOLE|console]] window. +* '''Note: QB64''' will not remove CHR$(0) from the end of LINE INPUT string return values like QBasic did. +{{PageExamples}} ''Example:'' Preventing screen roll after an input entry on the bottom 2 screen rows. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 diff --git a/internal/help/LINE_INPUT_(file_statement).txt b/internal/help/LINE_INPUT_(file_statement).txt index 4c87bf40d..24fe10717 100644 --- a/internal/help/LINE_INPUT_(file_statement).txt +++ b/internal/help/LINE_INPUT_(file_statement).txt @@ -1,30 +1,31 @@ -The '''LINE INPUT #''' file statement reads an entire file line as one string variable value. - +The '''LINE INPUT #''' file statement reads an entire line from a text file into a string variable. {{PageSyntax}} -:: '''LINE INPUT''' '''#'''''filenumber&''''',''' ''textlinereturn$'' +: '''LINE INPUT''' '''#'''{{Parameter|fileNumber&}}''',''' ''stringVariable$'' {{Parameters}} -* ''filenumber'' is the [[INTEGER]] number of the file previously opened [[AS]]. -* Statement [[STRING]] variable returns ''text line'' of the file being read ending at [[ASCII#Control_Characters|CRLF]] characters. +* {{Parameter|fileNumber&}} is the [[INTEGER]] number of the file previously opened with the [[OPEN]] statement. +* {{Parameter|stringVariable$}} holds the text line read from the file. -''Description:'' -* Reads a file using the filenumber [[OPEN]]ed in the [[INPUT (file mode)]] or GL [[BINARY]] file mode as one file line text string. +{{PageDescription}} +* Reads a file using the {{Parameter|fileNumber&}} [[OPEN]]ed in the [[INPUT (file mode)]] or [[BINARY]] file mode as one file line text string. +* '''NOTE:''' [[LINE INPUT (file statement)|LINE INPUT]] will work faster in [[BINARY]] mode than in [[INPUT (file mode)|INPUT]] mode. +** Using '''LINE INPUT #''' in [[BINARY]] mode is possible in '''version 1.000 and up''' * Can be used with [[EOF]] to count the number of lines of data (records) in a file using a loop. * Use the [[EOF]] function to avoid going past the end of a file and creating an error. -* LINE INPUT # can even retain the original quotation marks in text. -* '''Note: QB64''' will NOT remove CHR$(0) from the end of LINE INPUT # string return values like Qbasic did. -* '''NOTE: [[LINE INPUT (file statement)|LINE INPUT]] will work faster in [[BINARY]] than [[INPUT (file mode)|INPUT]] mode in QB64 to stay compatible with QB.''' +* '''LINE INPUT #''' can even retain the original quotation marks in text. +* '''Note: QB64''' will not remove CHR$(0) from the end of '''LINE INPUT #''' string return values like QBasic did. {{PageErrors}} -* '''If QB64 or QB 4.5 give "Input past End of file" errors, check for CHR$(26) in the files being read!''' -* '''Warning! Files must exist to open them in INPUT mode! Use [[_FILEEXISTS]] to avoid program [[ERROR Codes|errors]]!''' +* '''If an "Input past End of file" error occurs, check for CHR$(26) (end of file character) in the files being read.''' +* '''Warning: files must exist to be opened in '''INPUT''' mode. Use [[_FILEEXISTS]] to avoid program [[ERROR Codes|errors]].''' +{{PageExamples}} ''Example:'' Finding the number of filenames listed in a file to dimension an array to hold them. {{CodeStart}} '' '' {{Cl|REDIM}} FileArray$(100) 'create {{Cl|$DYNAMIC|dynamic}} array @@ -42,12 +43,12 @@ The '''LINE INPUT #''' file statement reads an entire file line as one string va {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[OPEN]], [[CLOSE]] * [[INPUT (file mode)]], [[INPUT (file statement)|INPUT #]], [[INPUT$]] {{text|(file input)}} * [[INPUT]], [[LINE INPUT]], [[INPUT$]] {{text|(keyboard input)}} * [[_FILEEXISTS]], [[_DIREXISTS]] -* [[FILELIST$]] (Function replacement for [[FILES]]) +* [[FILELIST$]] (member-contributed function replacement for [[FILES]]) {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LOC.txt b/internal/help/LOC.txt index b4a6333cd..08dee0830 100644 --- a/internal/help/LOC.txt +++ b/internal/help/LOC.txt @@ -1,17 +1,17 @@ -The '''LOC''' function returns the status of a Serial(COM) port receive buffer or the current byte position in a file. - +The [[LOC]] function returns the status of a serial (COM) port received buffer or the current byte position in an open file. {{PageSyntax}} -:: bytes% = LOC(open_number) +: {{Parameter|bytes%}} = LOC({{Parameter|fileOrPortNumber%}}) -* The parameter used is the number used in the port [[OPEN]] AS statement. -* Returns 0 if the buffer is empty. Any value above 0 indicates COM has received data. +* {{Parameter|fileOrPortNumber%}} is the number used in the port [[OPEN]] AS statement. +* Returns 0 if the buffer is empty. Any value above 0 indicates the COM port has received data. * Use it in conjunction with [[INPUT$]] to get the data bytes received. -* Can also be used for the current position in a file routine. See: [[SEEK]] +* Can also be used to read the current position in a file routine. See [[SEEK]]. +{{PageExamples}} ''Example:'' Reading and writing from a COM port opened in Basic. {{CodeStart}} '' '' {{Cl|OPEN}} "{{Cl|OPEN_COM|COM}}1: 9600,N,8,1,OP0" {{Cl|FOR (file statement)|FOR}} {{Cl|RANDOM}} {{Cl|AS}} #1 {{Cl|LEN}} = 2048 ' random mode = input and output @@ -27,8 +27,8 @@ The '''LOC''' function returns the status of a Serial(COM) port receive buffer o {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[PRINT]], [[OPEN COM]], [[PRINT (file statement)]] - +* [[SEEK]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LOCATE.txt b/internal/help/LOCATE.txt index 56d9bb962..a6a7251a6 100644 --- a/internal/help/LOCATE.txt +++ b/internal/help/LOCATE.txt @@ -1,28 +1,29 @@ -The '''LOCATE''' statement locates the screen text row and column positions for a {{KW|PRINT}} or {{KW|INPUT}} procedure. +The [[LOCATE]] statement locates the screen text row and column positions for a [[PRINT]] or [[INPUT]] procedure. {{PageSyntax}} -::: '''LOCATE''' [''row%''][, ''column%''] [, ''cursor%''][, ''cursor_start%'', ''cursor_stop%''] +: [[LOCATE]] [{{Parameter|row%}}][, {{Parameter|column%}}] [, {{Parameter|cursor%}}][, {{Parameter|cursorStart%}}, {{Parameter|cursorStop%}}] {{Parameters}} -* optional text ''row'' [[INTEGER]] values are from 1 to the 25, 43 or 50 in [[SCREEN]] 0 and 25 in most other graphic screen modes, except screens 11 and 12 which can have 30 or 60. -* optional ''column'' [[INTEGER]] values are from 1 to 40 or 80 in [[SCREEN]] 0 and 80 in all other legacy screen modes. -* optional ''cursor'' value can be 0 to turn the cursor off or 1 to turn it on when using the [[INPUT$]] or [[INKEY$]] key entry functions only. -* optional ''cursorstart'' and ''cursorstop'' values define the shape of the cursor by setting the start and stop scanline (0-8 pixels) for the cursor character. +* optional text {{Parameter|row%}} [[INTEGER]] values are from 1 to 25, 43 or 50 in [[SCREEN]] 0 and 25 in most other legacy graphic screen modes, except screens 11 and 12 which can have 30 or 60 rows. +* optional {{Parameter|column%}} [[INTEGER]] values are from 1 to 40 or 80 in [[SCREEN]] 0 and 80 in all other legacy screen modes. +* optional {{Parameter|cursor%}} value can be 0 to turn displaying the cursor off or 1 to turn it on. +* optional {{Parameter|cursorStart%}} and {{Parameter|cursorStop%}} values define the shape of the cursor by setting the start and stop scanline (values range from 0 to 31) for the cursor character. -''Usage:'' +{{PageDescription}} * [[WIDTH]] statement can be used to determine the text width and height in [[SCREEN]] 0 and height of 30 or 60 in [[SCREEN]] 11 or 12. -* In [[_NEWIMAGE]] graphic screen text ''rows'' are calculated as [[_HEIGHT]] \ 16 except when a [[_FONT]] is used. Use [[_FONTHEIGHT]] to calculate font rows. +* In [[_NEWIMAGE]] graphic screen the number of text ''rows'' are calculated as [[_HEIGHT]] \ 16 except when a [[_FONT]] is used. Use [[_FONTHEIGHT]] to calculate font rows. * [[_NEWIMAGE]] graphic screen text ''columns'' are calculated as [[_WIDTH (function)|_WIDTH]] \ 8 except when a [[_FONT]] is used. Use [[_PRINTWIDTH]] to measure a line of font text. * The text ''row'' position is not required if the [[PRINT]] is going to be on the next row. The [[comma]] and a ''column'' value are required to set the column. -* If only the ''row'' parameter is given, then the column position remains the same. '''Neither ''row'' or ''column'' parameter can be 0!''' +* If only the ''row'' parameter is given, then the column position remains the same. '''Neither ''row'' or ''column'' parameter can be 0.''' * When [[PRINT]]ing on the bottom 2 ''rows'', use a [[semicolon]] after the PRINT expression to avoid a screen roll. -* If the ''cursor start'' line is given, the ''cursor stop'' line must also be given. A wider range between them produces a taller cursor. +* If the {{Parameter|cursorStart%}} line is given, the {{Parameter|cursorStop%}} line must also be given. A wider range between them produces a taller cursor. -Example: Moving the cursor around (now you can finally create a Commodore 64 emulator!). '''Default SCREEN 0 ONLY!''' +{{PageExamples}} +''Example:'' Moving the cursor around (now you can finally create a Commodore 64 emulator!). '''Default SCREEN 0 only:''' {{CodeStart}} '' '' crx = 10 cry = 10 @@ -43,7 +44,6 @@ LOOP '' '' - {{PageSeeAlso}} * [[CSRLIN]], [[POS]] {{text|(cursor position)}} * [[SCREEN]], [[PRINT]], [[COLOR]] diff --git a/internal/help/LOCK.txt b/internal/help/LOCK.txt index 6f867bbe1..872a7cef5 100644 --- a/internal/help/LOCK.txt +++ b/internal/help/LOCK.txt @@ -1,10 +1,10 @@ -The {{KW|LOCK}} statement restricts access to parts of a file by other programs or processes. +The [[LOCK]] statement restricts access to parts of a file by other programs or processes. {{PageSyntax}} -:{{KW|LOCK}} [#]{{Parameter|fileNumber%}} -:{{KW|LOCK}} [#]{{Parameter|fileNumber%}}, {{Parameter|record&}} -:{{KW|LOCK}} [#]{{Parameter|fileNumber%}}, [{{Parameter|firstRecord&}}] TO {{Parameter|lastRecord&}} +:[[LOCK]] [#]{{Parameter|fileNumber%}} +:[[LOCK]] [#]{{Parameter|fileNumber%}}, {{Parameter|record&}} +:[[LOCK]] [#]{{Parameter|fileNumber%}}, [{{Parameter|firstRecord&}}] TO {{Parameter|lastRecord&}} {{PageDescription}} @@ -13,16 +13,19 @@ The {{KW|LOCK}} statement restricts access to parts of a file by other programs * In the second syntax, {{Parameter|record&}} is the record number of the file to lock. * In the third syntax, the records or bytes in the range [{{Parameter|firstRecord&}},{{Parameter|lastRecord&}}] are locked. If {{Parameter|firstRecord&}} is omitted, it is assumed to be one (the first record or byte). * For files opened in [[BINARY]] mode, each record corresponds to a single byte. -* LOCK and [[UNLOCK]] statements are always used in pairs and each statement must match the other one. +* [[LOCK]] and [[UNLOCK]] statements are always used in pairs and each statement must match the other one. * Files must be unlocked using [[UNLOCK]] before other programs can access them, and before the file is closed. -* Requires DOS '''SHARED.EXE''' be run for QBasic to use networking access modes. -* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] +* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword not supported in Linux or macOS versions]] + + +==QBasic/QuickBasic== +* Required DOS '''SHARED.EXE''' to be run for QBasic to use networking access modes. No longer required. {{PageSeeAlso}} -* {{KW|UNLOCK}} -* {{KW|OPEN}} -* {{KW|ACCESS}} +* [[UNLOCK]] +* [[OPEN]] +* [[ACCESS]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LOF.txt b/internal/help/LOF.txt index 29dc260e1..9f453f22e 100644 --- a/internal/help/LOF.txt +++ b/internal/help/LOF.txt @@ -1,18 +1,20 @@ -The '''LOF''' Function is used to find the length of an [[OPEN]] file in bytes. +The [[LOF]] function is used to find the length of an [[OPEN]] file in bytes. {{PageSyntax}} -:: bytes = LOF(filenumber) +: ''totalBytes&'' = [[LOF]]([#]{{Parameter|fileNumber}}) -* LOF returns the number of bytes in an OPENed designated filenumber. File is empty if it returns 0. -* Filenumber is the number of the opened file. # is not required. +{{PageDescription}} +* LOF returns the number of bytes in an [[OPEN]]ed designated {{Parameter|fileNumber}}. File is empty if it returns 0. +* {{Parameter|fileNumber}} is the number of the opened file. '''#''' is not required. * Often used to determine the number of records in a [[RANDOM]] access file. * Can also be used to avoid reading an empty file, which would create an error. -* LOF in '''QB64''' can return up to 9223372036 gigabyte file sizes. +* LOF in '''QB64''' can return up to 9 GB (9,223,372,036 bytes) file sizes. +{{PageExamples}} ''Example:'' Finding the number of records in a RANDOM file using a [[TYPE]] variable. {{CodeStart}} @@ -21,10 +23,7 @@ The '''LOF''' Function is used to find the length of an [[OPEN]] file in bytes. {{CodeEnd}} -''See Example:'' [[INPUT (file mode)]] - - -''See also:'' +{{PageSeeAlso}} * [[LEN]], [[EOF]], [[BINARY]], [[RANDOM]], [[TYPE]] diff --git a/internal/help/LOG.txt b/internal/help/LOG.txt index 6530c5c3a..4330ecdbb 100644 --- a/internal/help/LOG.txt +++ b/internal/help/LOG.txt @@ -1,18 +1,18 @@ -The '''LOG''' math function returns the natural logarithm of a specified numerical value. - +The [[LOG]] math function returns the natural logarithm of a specified numerical value. {{PageSyntax}} -:: logarithm = LOG(value) +: {{Parameter|logarithm!}} = [[LOG]]({{Parameter|value}}) - -* Value parameter MUST be greater than 0! [[ERROR Codes|"Illegal function call" error]] using negative or zero values! +{{PageDescription}} +* {{Parameter|value}} MUST be greater than 0. [[ERROR Codes|"Illegal function call" error]] occurs if negative or zero values are used. * The natural logarithm is the logarithm to the base '''e = 2.718282''' (approximately). * The natural logarithm of ''a'' is defined as the integral from 1 to ''a'' of dx/x. * Returns are default [[SINGLE]] precision unless the value parameter uses [[DOUBLE]] precision. +{{PageExamples}} ''Example 1:'' [[FUNCTION]] to find the base ten logarithm of a numerical value. {{CodeStart}} FUNCTION Log10#(value AS DOUBLE) {{Cl|STATIC}} @@ -37,8 +37,7 @@ END FUNCTION : ''Explanation:'' The LOG of a '''positive''' [[INTEGER]] value is divided by the LOG of 2 to determine the number of binary digits that will be returned. The FOR loop compares the value with the exponents of two and determines if a bit is ON or OFF as "1" or "0". -''See also:'' - +{{PageSeeAlso}} *[[EXP]], [[&B]] (binary number) *[http://qb64.net/wiki/index.php?title=Mathematical_Operations#Derived_Mathematical_Functions Derived Trigonometric Functions] diff --git a/internal/help/LONG.txt b/internal/help/LONG.txt index 0f5d7026a..16800aea6 100644 --- a/internal/help/LONG.txt +++ b/internal/help/LONG.txt @@ -1,22 +1,22 @@ -'''LONG''' defines a variable as a 4 byte number type definition for larger [[INTEGER]] values. +[[LONG]] defines a variable as a 4 byte number type definition for larger [[INTEGER]] values. {{PageSyntax}} -:: DIM ''variable'' AS LONG +: [[DIM]] {{Parameter|variable}} AS [[LONG]] -* Qbasic LONG Integer values can be from -2147483648 to 2147483647. -* '''QB64''' [[_UNSIGNED]] Long Integer values range from 0 to 4294967295. -* '''QB64''' [[_UNSIGNED]] [[_INTEGER64]] values can range from 0 to 18446744073709551615. -* Decimal point values received will be rounded to the nearest whole number. +* [[LONG]] integer values range from -2147483648 to 2147483647. +* '''QB64''''s [[_UNSIGNED]] [[LONG]] integer values range from 0 to 4294967295. +* '''QB64''' [[_UNSIGNED]] [[_INTEGER64]] values range from 0 to 18446744073709551615. +* Decimal point values assigned to a [[LONG]] variable will be rounded to the nearest whole number. * The LONG variable type suffix is & or ~& for [[_UNSIGNED]]. Suffix can also be placed after a literal or hexadecimal numerical value. * [[_INTEGER64]] uses the '''&&''' or '''~&&''' [[_UNSIGNED]] suffix. * Values can be converted to 4 byte [[ASCII]] string values using [[MKL$]] and back with [[CVL]]. -* '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' -* '''Warning: Qbasic keyword names cannot be used as numerical variable names with or without the type suffix!''' +* '''When a variable has not been assigned or has no type suffix, the type defaults to [[SINGLE]].''' +* '''Warning: QBasic keyword names cannot be used as numerical variable names with or without the type suffix.''' -''See also:'' +{{PageSeeAlso}} * [[DIM]], [[DEFLNG]] * [[LEN]], [[CLNG]] * [[MKL$]], [[CVL]] diff --git a/internal/help/LPOS.txt b/internal/help/LPOS.txt index c7bf91c07..98d5685c3 100644 --- a/internal/help/LPOS.txt +++ b/internal/help/LPOS.txt @@ -1,8 +1,8 @@ -The {{KW|LPOS}} function returns the current LPT printer head position. +The [[LPOS]] function returns the current LPT printer head position. {{PageSyntax}} -:''result%'' = {{KW|LPOS}}({{Parameter|index%}}) +: {{Parameter|result%}} = [[LPOS]]({{Parameter|index%}}) {{PageDescription}} @@ -40,6 +40,7 @@ The {{KW|LPOS}} function returns the current LPT printer head position. {{PageSeeAlso}} +* [[LPRINT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/LPRINT.txt b/internal/help/LPRINT.txt index 5724494c6..14a60eb0c 100644 --- a/internal/help/LPRINT.txt +++ b/internal/help/LPRINT.txt @@ -1,19 +1,19 @@ -The {{KW|LPRINT}} statement sends string text or numerical values to a parallel port(LPT1) printer in Qbasic or a USB printer in '''QB64'''. +The [[LPRINT]] statement sends string text or numerical values to a parallel port (LPT1) printer in QBasic or a USB printer in '''QB64'''. {{PageSyntax}} -:{{KW|LPRINT}} [{{Parameter|expression}}] [{;|,}] +:[[LPRINT]] [{{Parameter|expression}}] [{;|,}] {{PageDescription}} * {{Parameter|expression}} is one or more text or numerical expressions separated by a semi-colon (;) or comma (,). * Syntax is the same as [[PRINT]], but cannot use a port number. -* Program does not have to [[OPEN]] the LPT1: parallel port. In fact that is NOT recommended! -* Assumes a 80 character wide page unless a [[WIDTH|WIDTH LPRINT]] statement is used. '''[[Keywords currently not supported by QB64|WIDTH LPRINT is currently NOT supported in QB64!]]''' +* Program does not have to [[OPEN]] the LPT1: parallel port. +* Assumes a 80 character wide page. '''[[Keywords currently not supported by QB64|WIDTH LPRINT is not supported in QB64.]]''' * [[LPRINT USING]] can print formatted text data to a page identically to how [[PRINT USING]] formats a program screen. * [[COLOR]]ed text and images can be printed using [[_PRINTIMAGE]] which stretches them to fit the default printer's paper size. -* LPRINT will only print to the DEFAULT USB or LPT printer that works in Windows. '''[[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]]''' -* Note: Printer Escape codes starting with [[CHR$]](27) will not work with LPRINT and may produce text printing errors. +* LPRINT will only print to the default USB or LPT printer set up in Windows. '''[[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]]''' +* Note: Printer ''escape codes'' starting with [[CHR$]](27) will not work with LPRINT and may produce text printing errors. {{PageSeeAlso}} diff --git a/internal/help/LPRINT_USING.txt b/internal/help/LPRINT_USING.txt index a0de286f0..d3755d8a1 100644 --- a/internal/help/LPRINT_USING.txt +++ b/internal/help/LPRINT_USING.txt @@ -2,20 +2,20 @@ The [[LPRINT USING]] statement sends formatted data to LPT1, the parallel port p {{PageSyntax}} -:: '''LPRINT''' [''text$''{;|,}] '''USING ''template$''; ''variable'''''[; ...][{;|,}] +: '''LPRINT''' [''text$''{;|,}] '''USING''' {{Parameter|template$}}; {{Parameter|variable}}[; ...][{;|,}] {{Parameters}} -* Literal or variable [[STRING]] ''text$'' can be placed between [[LPRINT]] and USING or it can be included in the ''template''. -* A [[semicolon]] or [[comma]] may follow the ''text'' to stop or tab the print cursor before the ''template'' [[LPRINT]]. -* The literal or variable [[STRING]] ''template'' should use the template symbols to display each variable [[type]] in the list following it. -* The list of data ''variables'' used in the ''template'' are '''separated by semicolons''' after the template string value. +* Literal or variable [[STRING]] ''text$'' can be placed between [[LPRINT]] and USING or it can be included in the {{Parameter|template$}}. +* A [[semicolon]] or [[comma]] may follow the {{Parameter|text$}} to stop or tab the print cursor before the {{Parameter|template$}} [[LPRINT]]. +* The literal or variable [[STRING]] {{Parameter|template$}} should use the template symbols to display each variable [[type]] in the list following it. +* The list of data ''variables'' used in the {{Parameter|template$}} are '''separated by semicolons''' after the template string value. * A [[semicolon]] or [[comma]] may follow the variable list to stop or tab the print cursor for pending prints. -''Usage:'' -* The ''variables'' should be listed in the order that they are used in the template from left to right. -* '''If the ''template'' string is omitted or symbols don't match the ''variable(s)'' an "Illegal Function Call" [[ERROR Codes|ERROR]] will occur!''' +{{PageDescription}} +* The ''variable'' list should be listed in the order that they are used in the template from left to right. +* '''If the ''template'' string is omitted or symbols don't match the ''variable(s)'' an "Illegal Function Call" [[ERROR Codes|ERROR]] will occur.''' * No more than 25 # digit places are allowed in a template number or an [[ERROR Codes|error]] will occur. * Can convert numerical exponential or [[scientific notation]] values to normal decimal point values using less digits. * '''NOTE:''' If the numerical value exceeds the template's digit range a % symbol will appear in the leftmost digit area. diff --git a/internal/help/LSET.txt b/internal/help/LSET.txt index 57e2014b9..db6847568 100644 --- a/internal/help/LSET.txt +++ b/internal/help/LSET.txt @@ -1,17 +1,18 @@ -'''LSET''' left-justifies a fixed length string expression based on the size of the [[STRING]] variable and string expression. - +[[LSET]] left-justifies a fixed length string expression based on the size of the [[STRING]] variable and string expression. {{PageSyntax}} -: LSET {string_variable = string_expression | string_expression1 = string_expression2} +: [[LSET]] {stringVariable = stringExpression | stringExpression1 = stringExpression2} +{{PageDescription}} * If the string expression is longer than a fixed length string variable the value is truncated from the right side in LSET or [[RSET]]. * If the LSET string expression is smaller, spaces will occupy the extra positions to the right in the string. * LSET can be used with a [[FIELD]] or [[TYPE]] definition to set the buffer position before a [[PUT]]. -''Example 1:'' Using LSET with a [[FIELD]] definition. Note: May create an empty(unchanged) file that can be deleted. +{{PageExamples}} +''Example 1:'' Using LSET with a [[FIELD]] definition. Note: May create an empty (unchanged) file that can be deleted. {{CodeStart}} '' '' {{Cl|OPEN}} "testfile.dat" FOR {{Cl|RANDOM}} AS #1 {{Cl|LEN}} = 15 @@ -53,9 +54,7 @@ you.head: ACHES {{OutputEnd}} - - -''See also:'' +{{PageSeeAlso}} * [[RSET]], [[RTRIM$]] * [[FIELD]], [[TYPE]] diff --git a/internal/help/LTRIM$.txt b/internal/help/LTRIM$.txt index 8bca62680..556087640 100644 --- a/internal/help/LTRIM$.txt +++ b/internal/help/LTRIM$.txt @@ -1,17 +1,18 @@ -The {{KW|LTRIM$}} function removes leading space characters from a {{KW|STRING}} value. +The [[LTRIM$]] function removes leading space characters from a [[STRING]] value. {{PageSyntax}} -:''return$'' = {{KW|LTRIM$}}({{Parameter|value$}}) +:{{Parameter|return$}} = [[LTRIM$]]({{Parameter|text$}}) {{PageDescription}} -* {{Parameter|value$}} is the {{KW|STRING}} value to trim. -* If {{Parameter|value$}} contains no leading space characters, {{Parameter|value$}} is returned unchanged. -* Convert fixed length {{KW|STRING}} values by using a different {{parameter|return$}} variable. -* Can be used to trim the leading space of a positive numerical value converted to a string value by {{KW|STR$}}. +* {{Parameter|text$}} is the [[STRING]] value to trim. +* If {{Parameter|text$}} contains no leading space characters, it is returned unchanged. +* Convert fixed length [[STRING]] values by using a different {{parameter|return$}} variable. +* Can be used to trim the leading space of a positive numerical value converted to a string value by [[STR$]]. +{{PageExamples}} ''Example 1:'' Trimming a positive string number. {{CodeStart}} value = 12345 diff --git a/internal/help/MID$.txt b/internal/help/MID$.txt index 792a23aab..bdca9a7ea 100644 --- a/internal/help/MID$.txt +++ b/internal/help/MID$.txt @@ -1,24 +1,28 @@ -The '''MID$''' function returns a portion of a [[STRING]]'s value from any position inside a string. - +The [[MID$]] function returns a portion of a [[STRING|string]]. {{PageSyntax}} -:: MID$(''stringvalue$'', ''startposition%''[, ''bytes%'']) +: {{Parameter|portion$}} = MID$({{Parameter|stringValue$}}, {{Parameter|startPosition%}}[, {{Parameter|bytes%}}]) -''[[Parameters]]:'' -* ''stringvalue'' can be any literal or variable [[STRING]] value having a length. See [[LEN]]. -* ''startposition'' designates the non-zero position of the first character to be returned by the function. -* ''bytes'' (optional) tells the function how many characters to return including the first character when it is used. - -''Usage:'' -* When the ''bytes'' value is not used the function returns the remainder of the string from the starting character position. -* Number of character ''bytes'' should be within the string's [[LEN|length]] from the start position, but will only return the string's remainder when exceeded. -* If the ''bytes'' value is 0 or the ''start position'' is 0 or greater than the [[LEN|length]] of the string, nothing is returned (no error). -* In QBasic the ''start position'' cannot be zero(0) or an [[ERROR Codes|Illegal function call error]] will occur. -* In '''QB64''' [[ASC]] string byte position reads are about '''5 times faster''' than MID$ when parsing strings. See ''Example 2'' below. +{{Parameters}} +* {{Parameter|stringValue$}} can be any literal or variable non-empty [[STRING]] value. Use [[LEN]] to check the length of a string. +* {{Parameter|startPosition%}} designates the non-zero position of the first character to be returned by the function. +* {{Parameter|bytes%}} (optional) tells the function how many characters to return including the first character at {{Parameter|startPosition%}}. +{{PageDescription}} +* When the {{Parameter|bytes%}} value is not passed, the function returns the remainder of the string from the starting character position. +* Number of character {{Parameter|bytes%}} should be within the string's [[LEN|length]] from the start position, but will only return the string's remainder when exceeded. +* If the {{Parameter|bytes%}} value is 0 or the {{Parameter|startPosition%}} is 0 or greater than the [[LEN|length]] of the string, an empty string is returned (no error is triggered). +* In '''QB64''', [[ASC]] string byte position reads are about '''5 times faster''' than MID$ when parsing strings. See ''Example 2'' below. + + +==QBasic/QuickBASIC== +* In QBasic the {{Parameter|startPosition%}} could not be zero (0) or an [[ERROR Codes|Illegal function call error]] would occur. + + +{{PageExamples}} ''Example 1:'' Getting the hour and minutes from [[TIME$]] {{CodeStart}} '' '' {{Cl|PRINT}} {{Cl|TIME$}} @@ -91,7 +95,7 @@ t5# = {{Cl|TIMER}} 0.494141 seconds for _MEMGET String 0.494141 seconds for _MEMGET Byte {{OutputEnd}} -: ''Note:'' [[_MEMGET]] can be used with [[$CHECKING]]:OFF to cut the parsing speed even more! [[STRING]] * 1 or [[_BYTE]] are similar speeds. +: ''Note:'' [[_MEMGET]] can be used with [[$CHECKING]]:OFF to cut the parsing speed even more. [[STRING]] * 1 or [[_BYTE]] are similar speeds. ''See also:'' diff --git a/internal/help/Mathematical_Operations.txt b/internal/help/Mathematical_Operations.txt index d6a49ffcc..cf8625eb3 100644 --- a/internal/help/Mathematical_Operations.txt +++ b/internal/help/Mathematical_Operations.txt @@ -5,10 +5,10 @@ ==Basic and QB64 Numerical Types== <center>'''Qbasic Number Types'''</center> -* [[INTEGER]] ['''%''']: 2 Byte signed whole number values from -32768 to 32767. 0 to 65535 unsigned. (currently not checked in QB64) +* [[INTEGER]] ['''%''']: 2 Byte signed whole number values from -32768 to 32767. 0 to 65535 unsigned. (not checked in QB64) * [[LONG]] ['''&''']: 4 byte signed whole number values from -2147483648 to 2147483647. 0 to 4294967295 unsigned. -* [[SINGLE]] ['''!''']: 4 byte signed floating decimal point values of up to 7 decimal place accuracy. '''Cannot be unsigned!''' -* [[DOUBLE]] [#]: 8 byte signed floating decimal point values of up to 15 decimal place accuracy. '''Cannot be unsigned!''' +* [[SINGLE]] ['''!''']: 4 byte signed floating decimal point values of up to 7 decimal place accuracy. '''Cannot be unsigned.''' +* [[DOUBLE]] [#]: 8 byte signed floating decimal point values of up to 15 decimal place accuracy. '''Cannot be unsigned.''' * To get '''one byte''' values, can use an [[ASCII]] [[STRING]] character to represent values from 0 to 255 as in [[BINARY]] files. @@ -17,8 +17,8 @@ * [[_BIT]] ['''`''']: 1 bit signed whole number values of 0 or -1 signed or 0 or 1 unsigned. [[_BIT]] * 8 can hold a signed or unsigned [[_BYTE|byte]] value. * [[_BYTE]] ['''%%''']: 1 byte signed whole number values from -128 to 127. Unsigned values from 0 to 255. * [[_INTEGER64]] ['''&&''']: 8 byte signed whole number values from -9223372036854775808 to 9223372036854775807 -* [[_FLOAT]] [##]: currently set as 10 byte signed floating decimal point values up to 1.1897E+4932. '''Cannot be unsigned!''' -* [[_OFFSET]] [%&]: undefined flexable length integer offset values used in [[DECLARE DYNAMIC LIBRARY]] declarations ONLY. +* [[_FLOAT]] [##]: currently set as 10 byte signed floating decimal point values up to 1.1897E+4932. '''Cannot be unsigned.''' +* [[_OFFSET]] [%&]: undefined flexable length integer offset values used in [[DECLARE DYNAMIC LIBRARY]] declarations. <center>'''Signed and Unsigned Integer Values'''</center> @@ -30,7 +30,7 @@ Negative (signed) numerical values can affect calculations when using any of the ::::* '''QB64:''' [[_UNSIGNED]] in a [[DIM]], [[AS]] or [[_DEFINE]] statement for only positive [[INTEGER]] values. -::[[_UNSIGNED]] integer, byte and bit variable values can use the tilde ~ suffix before the type suffix to define the type. +[[_UNSIGNED]] integer, byte and bit variable values can use the tilde ~ suffix before the type suffix to define the type. <center>[[#toc|Return to Top]]</center> @@ -89,8 +89,9 @@ There is also an operator for '''exponential''' calculations. The exponential op |} -:'''''Note: Exponent fractions should be enclosed in () brackets in order to be treated as a root rather than as division!''''' -<center> '''Negative exponential values must be enclosed in () brackets with QB64 currently!'''</center> +===Notes=== +* Exponent fractions should be enclosed in () brackets in order to be treated as a root rather than as division. +* Negative exponential values must be enclosed in () brackets in QB64. <center>[[#toc|Return to Top]]</center> @@ -158,11 +159,11 @@ END FUNCTION '' '' {{TextEnd}} -<center>'''The numerical value of n in the [[LOG]](n) evaluation MUST be a positive value!'''</center> +<center>'''The numerical value of n in the [[LOG]](n) evaluation must be a positive value.'''</center> -<center>'''The numerical value of n in the [[EXP]](n) evaluation MUST be LESS than or equal to 88.02969!'''</center> +<center>'''The numerical value of n in the [[EXP]](n) evaluation must be less than or equal to 88.02969.'''</center> -<center>'''The numerical value of n in the [[SQR]](n) evaluation can NOT be a negative value!'''</center> +<center>'''The numerical value of n in the [[SQR]](n) evaluation ''cannot'' be a negative value.'''</center> <center>[[#toc|Return to Top]]</center> @@ -299,7 +300,7 @@ END FUNCTION '' '' ==Mathematical Logical Operators== -: The following logical operators compare numerical values using bitwise operations. The two numbers are compared by the number's [[Binary]] bits on and the result of the operation determines the value returned in decimal form. [[NOT]] checks one value and returns the opposite. It returns 0 if a value is not 0 and -1 if it is 0. See [[Binary]] for more on bitwise operations. +The following logical operators compare numerical values using bitwise operations. The two numbers are compared by the number's [[Binary]] bits on and the result of the operation determines the value returned in decimal form. [[NOT]] checks one value and returns the opposite. It returns 0 if a value is not 0 and -1 if it is 0. See [[Binary]] for more on bitwise operations. <center>'''Truth table of the 6 BASIC Logical Operators'''</center> @@ -312,7 +313,6 @@ END FUNCTION '' '' <center>[[#toc|Return to Top]]</center> - ==Relational Operators== Relational Operations are used to compare values in a Conditional [[IF...THEN]], [[SELECT CASE]], [[UNTIL]] or [[WHILE]] statement. @@ -346,7 +346,8 @@ Relational Operations are used to compare values in a Conditional [[IF...THEN]], | [[_ROUND]] || rounds to closest numerical integer value in '''QB64''' only. |} -::: '''Note: Each of the above functions define the value's type in addition to rounding the values.''' +===Note=== +* Each of the above functions define the value's type in addition to rounding the values. <center>[[#toc|Return to Top]]</center> @@ -400,7 +401,9 @@ Relational Operations are used to compare values in a Conditional [[IF...THEN]], <center>'''[[VAL]] converts [[STRING|string]] numbers to Decimal values.'''</center> -:VAL reads the string from left to right and converts numerical string values, - and . to decimal values until it finds a character other than those 3 characters. Commas are NOT read either! However HEXadecimal and OCTal base values can be read with [[&H]] or [[&O]]. +* VAL reads the string from left to right and converts numerical string values, - and . to decimal values until it finds a character other than those 3 characters. Commas are not read. +* HEXadecimal and OCTal base values can be read with [[&H]] or [[&O]]. + <center>'''The [[OCT$]] [[STRING|string]] function return can be converted to a decimal value using [[VAL]]("&O" + OCT$(n)).'''</center> @@ -412,6 +415,7 @@ Relational Operations are used to compare values in a Conditional [[IF...THEN]], <center>[[#toc|Return to Top]]</center> + ==Bits and Bytes== <center>'''[[_BIT|BITS]]'''</center> @@ -428,7 +432,7 @@ Relational Operations are used to compare values in a Conditional [[IF...THEN]], ::The big-endian method compares exponents of 2 <sup>7</sup> down to 2 <sup>0</sup> while the little-endian method does the opposite. <center>'''[[_BYTE|BYTES]]'''</center> -* [[INTEGER]] values consist of 2 bytes called the '''HI''' and '''LO''' bytes. Anytime that the number of binary digits is a multiple of 16 (2bytes, 4 bytes, etc.) and the HI byte's MSB is on(1), the value returned will be negative. Even with [[SINGLE]] or [[DOUBLE]] values! +* [[INTEGER]] values consist of 2 bytes called the '''HI''' and '''LO''' bytes. Anytime that the number of binary digits is a multiple of 16 (2bytes, 4 bytes, etc.) and the HI byte's MSB is on(1), the value returned will be negative, even with [[SINGLE]] or [[DOUBLE]] values. {{WhiteStart}} '''16 BIT INTEGER OR REGISTER''' '''AH (High Byte Bits) AL (Low Byte Bits)''' BIT: 15 14 13 12 11 10 9 8 | 7 6 5 4 3 2 1 0 @@ -496,10 +500,10 @@ Relational Operations are used to compare values in a Conditional [[IF...THEN]], * [[_OFFSET (function)]] returns the memory offset position as a flexible sized value for a designated variable. See [[Using _OFFSET]]. -<center>'''Warning: [[_OFFSET]] values cannot be reassigned to other variable [[TYPE|types]]!'''</center> +<center>'''Warning: [[_OFFSET]] values cannot be reassigned to other variable [[TYPE|types]].'''</center> -<center>'''[[_OFFSET]] values can currently only be used in conjunction with [[_MEM]]ory and [[DECLARE DYNAMIC LIBRARY]] procedures.'''</center> +<center>'''[[_OFFSET]] values can only be used in conjunction with [[_MEM]]ory and [[DECLARE DYNAMIC LIBRARY]] procedures.'''</center> ==References== ''See also:'' diff --git a/internal/help/NEXT.txt b/internal/help/NEXT.txt index 9b645a218..7b0e4af3e 100644 --- a/internal/help/NEXT.txt +++ b/internal/help/NEXT.txt @@ -1,25 +1,23 @@ -'''NEXT''' is used in a [[FOR...NEXT|FOR]] counter loop to progress through the loop count or to [[RESUME]] on the NEXT code line after an error. +[[NEXT]] is used in a [[FOR...NEXT|FOR]] counter loop to progress through the loop count. -{{PageSyntax}} -:: FOR i = 1 TO 10 -::. -::. 'loop code -::. -::'''NEXT''' [i] - -:OR -:: RESUME {'''NEXT'''|linenumber|linelabel} +{{PageSyntax}} +: [[FOR]] {{Parameter|counterVariable}} = {{Parameter|startValue}} [[TO]] {{Parameter|stopValue}} [{{KW|STEP}} {{Parameter|increment}}] +:: ''{code}'' +:: ⋮ +: [[NEXT]] [{{Parameter|counterVariable}}] -* NEXT is required in a FOR loop or a [[ERROR Codes|"FOR without NEXT" error]] will occur. -* The FOR variable name is not required after NEXT. -* NEXT can be grouped with other NEXTs in nested FOR loops using colons like NEXT: NEXT -* NEXT can also end more than one nested [[FOR...NEXT|FOR]] loop using comma separated variables like NEXT i, j -* NEXT increases the FOR loop count so the variable value AFTER the FOR loop will be one more count than the requested count. -* Also used in [[ON ERROR]] [[GOTO]] procedures after [[RESUME]] to return the program to the next code line only after an [[ERROR Codes|error]] occurs. +{{PageDescription}} +* [[NEXT]] is required in a FOR loop or a [[ERROR Codes|"FOR without NEXT" error]] will occur. +* The FOR variable name is not required after [[NEXT]]. +* [[NEXT]] can be grouped with other NEXTs in nested FOR loops using colons like [[NEXT]]: [[NEXT]] +* [[NEXT]] can also end more than one nested [[FOR...NEXT|FOR]] loop using comma separated variables like [[NEXT]] i, j +* [[NEXT]] increases the FOR loop count, so after the loop is over the counterVariable's value will be stopValue + 1 (or stopValue + increment). +* [[NEXT]] is also used with the [[RESUME]] statement. +{{PageExamples}} ''Example:'' Finding the FOR variable value AFTER a simple counter loop to 10. {{CodeStart}} '' '' FOR i = 1 TO 10 @@ -31,10 +29,10 @@ PRINT "AFTER the LOOP, NEXT makes the value of i ="; i '' '' {{OutputStart}} 1 2 3 4 5 6 7 8 9 10 AFTER the LOOP, NEXT makes the value of i = 11 {{OutputEnd}} -''Result:'' The last value of i = 11 although FOR only looped 10 times. '''Only use the count values while inside of the loop or compensate for this behavior in your code!''' +''Result:'' The last value of i = 11 although FOR only looped 10 times. '''Only use the count values while inside of the loop or compensate for this behavior in your code.''' -''See also:'' +{{PageSeeAlso}} * [[FOR...NEXT]] * [[DO...LOOP]] * [[RESUME|RESUME NEXT]] diff --git a/internal/help/ON_COM(n).txt b/internal/help/ON_COM(n).txt index 40e955a15..b1d57936b 100644 --- a/internal/help/ON_COM(n).txt +++ b/internal/help/ON_COM(n).txt @@ -1,3 +1,8 @@ +''This page is maintained for historic purposes. The functionality described below has not been implemented in QB64.'' + +---- + + ON COM(n) branches to a line number or label when there is a value in the serial port specified. @@ -7,7 +12,7 @@ ON COM(n) branches to a line number or label when there is a value in the serial {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not implemented in QB64!]]''' * n can be 1 or 2 and is the number of the serial port that is tested. * If a value exists in the port then the program branches to the linenumber or label specified. * The event handler must first be activated with [[COM|COM(n) ON]] diff --git a/internal/help/ON_PEN.txt b/internal/help/ON_PEN.txt index 902d4e023..2718ed9d7 100644 --- a/internal/help/ON_PEN.txt +++ b/internal/help/ON_PEN.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + '''ON PEN''' enables event handling for the lightpen. @@ -6,7 +12,7 @@ ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * Any activity on the lightpen will cause the program to branch to the specified labelorline. * [[PEN (statement)|PEN]] [[ON]] enables or resumes event trapping. * [[PEN (statement)|PEN]] [[OFF]] disables event trapping and event logging. diff --git a/internal/help/ON_PLAY(n).txt b/internal/help/ON_PLAY(n).txt index 6cf353990..160331117 100644 --- a/internal/help/ON_PLAY(n).txt +++ b/internal/help/ON_PLAY(n).txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + '''ON PLAY (n)''' is a event-trapping statement that specifies the line-number or label to branch to when the background music queue has too few notes. @@ -6,7 +12,7 @@ ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * You can use PLAY ON, PLAY OFF and PLAY STOP to resume event-trapping, disable it, or stop it (resumes with PLAY ON). diff --git a/internal/help/ON_UEVENT.txt b/internal/help/ON_UEVENT.txt index 23d015219..48dde2527 100644 --- a/internal/help/ON_UEVENT.txt +++ b/internal/help/ON_UEVENT.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The '''ON UEVENT''' statement allows a program to use a user defined event procedure. @@ -6,7 +12,7 @@ The '''ON UEVENT''' statement allows a program to use a user defined event proce :: ON UEVENT GOSUB {linenumber | linelabel} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]] NOTE: UEVENT procedures are only available in QuickBasic or PDS.''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]] NOTE: UEVENT procedures were only available in QuickBasic or PDS.''' * Any language(including assembly) compiler that can create interrupt service routines and uses code that can be linked with QuickBasic may be used. * Linenumber or linelabel argument is the line number or label of a [[GOSUB]] routine. * Allows your program to go to an event-handling routine when a user-defined event(often a hardware interrupt) occurs. diff --git a/internal/help/OPEN.txt b/internal/help/OPEN.txt index 8f2e70696..e44f768a4 100644 --- a/internal/help/OPEN.txt +++ b/internal/help/OPEN.txt @@ -1,98 +1,71 @@ -The '''OPEN''' statement is used to open a file or [[OPEN_COM|COM]] serial communications port for program input or output. +The [[OPEN]] statement is used to open a file or [[OPEN_COM|COM]] serial communications port for program input or output. -''Qbasic:'' {{PageSyntax}} - -::'''OPEN''' ''FileName$'' ['''FOR''' mode] [{{{KW|ACCESS}}|{{{KW|LOCK}}|SHARED}} [{READ|WRITE}] '''AS''' [#]''FileNumber&'' [LEN = ''recordLEN''] +{{PageSyntax}} +: [[OPEN]] {{Parameter|fileName$}} ['''FOR''' {{Parameter|mode}}] [{{{KW|ACCESS}}|{{{KW|LOCK}}|SHARED}} [{READ|WRITE}] [[AS]] [#]{{Parameter|fileNumber&}} [LEN = {{Parameter|recordLength}}] -''GW Basic'' {{PageSyntax}} -::'''OPEN''' ''modeletter$'', [#]''filenumber'', ''filename$''[, ''recordLEN''] +===Legacy ''GW-BASIC'' syntax=== +: [[OPEN]] {{Parameter|modeLetter$}}, [#]{{Parameter|fileNumber&}}, {{Parameter|fileName$}}[, {{Parameter|recordLength}}] -''Parameters:'' -* The ''fileName$'' is a [[STRING]] variable or literal file name (path optional) in quotes. -* FOR mode can be: [[APPEND]] (write to end), [[BINARY]] (read/write), [[INPUT (file mode)|INPUT]] (read), [[OUTPUT]] (write new) or [[RANDOM]] (read/write), . -* GW Basic's ''modeletter'' is a [[STRING]] variable or the letter "A", "B", "I", "O" or "R" designating the OPEN modes above. -* ''File number'' can be any '''positive''' [[INTEGER]] or [[LONG]] whole number value or an unused value determined by the [[FREEFILE]] function. -* [[LEN]] = or ''recordLEN'' is optional to denote the RANDOM(128 default) file record byte lengths or sequential(512 default) load buffer. +{{Parameters}} +* The {{Parameter|fileName$}} is a [[STRING]] variable or literal file name (path optional) in quotes. +* FOR mode can be: [[APPEND]] (write to end), [[BINARY]] (read/write), [[INPUT (file mode)|INPUT]] (read), [[OUTPUT]] (write new) or [[RANDOM]] (read/write). +* GW-BASIC's {{Parameter|modeLetter$}} is a [[STRING]] variable or the letter "A", "B", "I", "O" or "R" designating the OPEN modes above. +* {{Parameter|fileNumber&}} can be any '''positive''' [[INTEGER]] or [[LONG]] whole number value or an unused value determined by the [[FREEFILE]] function. +* [[LEN]] = or {{Parameter|recordLength}} is optional to denote the RANDOM file record byte length (default = 128) or sequential (default = 512) load buffer. {{PageDescription}} -* '''QB64''' can open as many files as your computer memory can handle. Qbasic could only open about 15 at a time. +* '''QB64''' can open as many files as your computer memory can handle. QBasic could only open about 15 at a time. * '''QB64 will allocate 4 bytes of memory for every possible file number up to the highest number used in a program.''' -* The ''mode'' defaults to RANDOM if the ''mode'' or FOR access statement is omitted. (see open modes described below) -* '''Only the ''filename'', ''file number'' and LEN = ''record length'' values can use variable values in the Qbasic OPEN syntax.''' +* {{Parameter|mode}} defaults to RANDOM if the {{Parameter|mode}} or FOR access statement is omitted. (see open modes described below) +* '''Only the {{Parameter|fileName$}}, {{Parameter|fileNumber&}} and LEN = {{Parameter|recordLength}} values can use variable values in the QBasic syntax.''' * If [[LEN]] = is ommitted, sequential file record sizes default to 512 and [[RANDOM]] to 128 bytes in Qbasic. -* '''QB64''' ''filenames'' can be up to 255(Windows) characters with no limit on file name extension length. +* {{Parameter|fileName$}} can be up to 255 characters with no limit on file name extension length in '''QB64'''. * Once a file or port is opened, it can be used in any program procedure using the assigned file number. -* The '''"SCRN:"''' device is now supported in all new GL versions after April 15, 2015(see Example 3). -* '''Devices such as "KYBD:", "CONS:", "COMn" and "LPTn:" are [[Keywords currently not supported by QB64|currently NOT supported in QB64!]]'''. +* The '''"SCRN:"''' device is supported in '''version 1.000 and up''' (see Example 3). +* '''Devices such as "KYBD:", "CONS:", "COMn" and "LPTn:" are [[Keywords currently not supported by QB64|not supported in QB64.]]'''. : '''Note:''' OPEN "LPTn" is not supported by QB64, but may be supported directly by your operating system. * [[OPEN COM]] can also be used for serial port access in '''QB64'''. {{PageErrors}} -* Illegal '''QB64''' Windows filename characters are ''' " * / \ | ? : < > '''. Multiple dots(periods) are allowed, but only the first one will be set. -* Illegal Qbasic Windows filename characters are ''' " * / \ + | ? [ ] , ; : < > ''' and more than one dot(period). +* Illegal '''QB64''' Windows filename characters are ''' " * / \ | ? : < > '''. Multiple dots (periods) are allowed. * Possible OPEN [[ERROR Codes|errors]] include "Bad file name or number", "Bad File Mode", "File Not Found" or "Path Not Found". -::: An OPEN file not found error may occur if [[CHR$]](0) to (31) are used in a Windows file name! -* Qbasic ''filenames'' must not exceed 12 characters(including dot) with a maximum of 3 file type extension characters using the DOS 8.3 naming convention limits. '''QB64''' does not have those file name limitations. +** An OPEN file not found error may occur if [[CHR$]](0) to (31) are used in a Windows file name. +* '''QB64''' does not have DOS file name limitations. -<center> ''' File ACCESS and LOCK Permissions'''</center> - -* [[ACCESS]] clause limits file access to READ, WRITE or READ WRITE on a network ONLY with DOS 3.1 or greater. +==Details== +===File ACCESS and LOCK Permissions=== +* [[ACCESS]] clause limits file access to READ, WRITE or READ WRITE on a network. * [[LOCK (access)|LOCK]] clause can specify SHARED or a LOCK READ or LOCK WRITE file lock in an OPEN statement working on a network. -* A separate [[LOCK]] statement can lock or [[UNLOCK]] file access on a network ONLY using a format that can lock specific records. -* ''Note:'' '''Qbasic''' ACCESS and LOCK clauses required that the DOS '''SHARED.EXE''' program be run for networking access. +* A separate [[LOCK]] statement can lock or [[UNLOCK]] file access on a network using a format that can lock specific records. +* If another process already has access to a specified file, program access is denied for that file OPEN access. A "Permission Denied" error 70 will be returned. A network program must be able to handle a denial of access error. + +===File Access Modes=== +* FOR mode can be: +** '''OUTPUT''': Sequential mode creates a new file or erases an existing file for new program output. Use [[WRITE (file statement)|WRITE #]] to write numerical or text data or [[PRINT (file statement)|PRINT #]] for text. '''OUTPUT clears files of all data''' and clears the receive buffer on other devices such as [[ON COM(n)|COM]]. +** '''APPEND''': Sequential mode creates a new file if it doesn't exist or appends program output to the end of an existing file. Use [[WRITE (file statement)|WRITE #]] for numerical or text data or [[PRINT (file statement)|PRINT #]] for text as in the OUTPUT mode. '''APPEND does not remove previous data.''' +** '''INPUT''' : Sequential mode '''only reads input''' from an existing file. '''[[ERROR Codes|File error]] if file does not exist.''' Use [[INPUT (file statement)|INPUT #]] for comma separated numerical or text data and [[LINE INPUT (file statement)|LINE INPUT #]] or [[INPUT$]] to only read text data. '''Use [[_FILEEXISTS]] or [[_DIREXISTS]] to avoid errors.''' +** '''BINARY''': Creates a new file when it doesn't exist or reads and writes to an existing binary file. Use [[GET|GET #]] to read or [[PUT|PUT #]] to write byte positions simultaneously. [[LEN]] = statements are ignored in this mode. +** '''RANDOM''': Creates a new file when it doesn't exist or reads or writes to an existing random file record. Use [[GET|GET #]] or [[PUT|PUT #]] to read or write to file records. A [[LEN]] = statement can define the byte size of a record (no LEN statement defaults to 128 bytes) +** Modes '''INPUT''', '''BINARY''' and '''RANDOM''' allow a file to be concurrently opened in a different mode and number. -<center>'''The 5 Qbasic File Access Modes:'''</center> - -* [[OUTPUT]]: Sequential mode creates a new file or erases an existing file for new program output. Use [[WRITE (file statement)|WRITE #]] to write numerical or text data or the [[PRINT (file statement)|PRINT #]] for text. '''OUTPUT clears files of all data''' and clears the receive buffer on other devices such as [[ON COM(n)|COM]]. -* [[APPEND]]: Sequential mode creates a new file if it doesn't exist or appends program output to the end of an existing file. Use [[WRITE (file statement)|WRITE #]] for numerical or text data or the [[PRINT (file statement)|PRINT #]] for text as in the OUTPUT mode. '''APPEND does not remove previous data.''' -* [[INPUT (file mode)|INPUT]] : Sequential mode '''only reads input''' from an existing file. '''[[ERROR Codes|File error]] if file does not exist!''' Use [[INPUT (file statement)|INPUT #]] for comma separated numerical or text data and [[LINE INPUT (file statement)|LINE INPUT #]] or [[INPUT$]] to only read text data. '''Use [[_FILEEXISTS]] or [[_DIREXISTS]] to avoid errors.''' +====GW-BASIC modes==== +* ''Mode letter'' is a variable or literal [[STRING]] letter value as one of the following: +** "A" = '''APPEND'''. +** "B" = '''BINARY'''. +** "I" = '''INPUT'''. +** "O" = '''OUTPUT'''. +** "R" = '''RANDOM'''. -* [[BINARY]]: Creates a new file when it doesn't exist or reads and writes to an existing binary file. Use [[GET|GET #]] to read or [[PUT|PUT #]] to write byte positions simultaneously. [[LEN]] = statements are ignored in this mode only. -* [[RANDOM]]: Creates a new file when it doesn't exist or reads or writes to an existing random file record. Use [[GET|GET #]] or [[PUT|PUT #]] to read or write to file records. A [[LEN]] = statement can define the byte size of a record (no LEN statement defaults to 128 bytes) - -* The [[INPUT (file mode)|INPUT]], [[BINARY]] and [[RANDOM]] file modes allow a file to be concurrently opened in a different mode and number. - - -<center>'''GW Basic OPEN statements'''</center> -:* ''Mode letter'' is a variable or literal [[STRING]] letter value as one of the following: - -::* "A" [[APPEND]] sequential mode allows data to be appended to an existing file using [[PRINT (file statement)|PRINT]] or [[WRITE (file statement)|WRITE]]. -::* "B" [[BINARY]] byte mode allows data to be read or written using [[GET]] or [[PUT]] -::* "I" [[INPUT (file mode)|INPUT]] sequential mode allows data to be read using [[INPUT (file statement)|INPUT]] or [[LINE INPUT (file statement)|LINE INPUT]] in '''existing''' files only. -::* "O" [[OUTPUT]] sequential mode creates or clears a file to write new data using [[PRINT (file statement)|PRINT]] or [[WRITE (file statement)|WRITE]]. -::* "R" [[RANDOM]] record mode allows [[TYPE]] or [[FIELD]] records to be read or written using [[GET]] or [[PUT]]. - - -:* ''File number'' can be any variable or literal [[INTEGER]] value between 1 and 255 or a [[FREEFILE]] value. -:* ''File name'' can be a variable or literal [[STRING]] file name value or port or device. -:* The '''"SCRN:"''' device is now supported in all new GL versions after April 15, 2015: {{text|'''OPEN "O", #1, "SCRN:"'''|green}} -:* '''Devices such as "KYBD:", "CONS:", "COMn" and "LPTn:" as file names are [[Keywords currently not supported by QB64|currently NOT supported in QB64!]]'''. -:: '''Note:''' OPEN "O", #1, "LPTn" is not supported by QB64, but may be supported directly by your operating system. -:* ''RecordLEN'' can be a variable or literal [[INTEGER]] value used in "R" mode only. -:* This type of OPEN allows the statement to be made using program variables only. A holdover for compatibility with GW Basic. -:* '''Note:''' Does not support any file [[ACCESS]] or [[LOCK]] restrictions. - - -<center> '''Comparing the GWBasic OPEN to a Qbasic OPEN statement:'''</center> - - -::::::::::GWBasic: OPEN "A", #1, Filename$ - -::::::::::Qbasic: OPEN Filename$ FOR APPEND AS #1 - -:Where Filename$ is the filename variable or a literal string name such as "Data1.DAT" is used. The Qbasic syntax cannot use a variable to change the OPEN mode so the programmer must determine it ahead of time. - - - -''Example 1:'' Function that displays errors and the number of errors in Qbasic filenames. Returns 0 when filename is OK. +{{PageExamples}} +''Example 1:'' Function that displays errors and the number of errors in QBasic filenames. Returns 0 when filename is OK. {{CodeStart}} file$ = "Hello,~1.mp3" 'example call below @@ -108,8 +81,8 @@ The '''OPEN''' statement is used to open a file or [[OPEN_COM|COM]] serial commu {{Cl|FOR...NEXT|FOR}} i% = 1 {{Cl|TO}} L 'check each filename character" code% = {{Cl|ASC}}({{Cl|MID$}}(Filename$, i%, 1)): {{Cl|COLOR}} 10 ' see ASCII codes {{Cl|SELECT CASE}} code% 'check for errors and highlight in red - {{Cl|CASE}} 34, 42 {{Cl|TO}} 44, 47, 58 {{Cl|TO}} 63, 91 {{Cl|TO}} 93, 124: E% = E% + 1: {{Cl|COLOR}} 12 ' '''Qbasic errors''' - '{{Cl|CASE}} 34, 42, 47, 58, 60, 62, 92, 124: E% = E% + 1: {{Cl|COLOR}} 12 ' '''QB64 errors''' + '{{Cl|CASE}} 34, 42 {{Cl|TO}} 44, 47, 58 {{Cl|TO}} 63, 91 {{Cl|TO}} 93, 124: E% = E% + 1: {{Cl|COLOR}} 12 ' '''QBasic errors''' + {{Cl|CASE}} 34, 42, 47, 58, 60, 62, 92, 124: E% = E% + 1: {{Cl|COLOR}} 12 ' '''QB64 errors''' {{Cl|CASE}} 46: dot% = dot% + 1: {{Cl|IF...THEN|IF}} dot% > 1 {{Cl|THEN}} E% = E% + 1: {{Cl|COLOR}} 12 {{Cl|END SELECT}} {{Cl|PRINT}} {{Cl|CHR$}}(code%); 'use {{Cl|LOCATE}} before {{Cl|FUNCTION}} call to place print @@ -117,33 +90,15 @@ The '''OPEN''' statement is used to open a file or [[OPEN_COM|COM]] serial commu CheckName% = E% {{Cl|END FUNCTION}} '' '' {{CodeEnd}} -''Note: The QB64 character error list is commented out. Comment out the Qbasic one when using the QB64 list. +''Note: The QBasic character error list is commented out and the function will return invalid filenames under QB64. {{OutputStart}} {{text|Hello|#54FC54}}{{text|,|red}}{{text|~1.mp3|#54FC54}} {{text|Total Errors|yellow}}<nowiki> = </nowiki>{{text|1|yellow}} {{OutputEnd}} -:''Note:'' The screen output displays filename characters in green except for red comma Qbasic error. +:''Note:'' The screen output displays filename characters in green except for red comma QBasic error. -''Example 2:'' A function that verifies that a file exists if it is NOT empty. Note: May create a file that is deleted if empty. -{{CodeStart}} '' '' -{{Cl|INPUT}} "Enter a file name: ", file$ -{{Cl|IF}} Exist%(file$) {{Cl|THEN}} {{Cl|OPEN}} file$ {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #1: found% = -1 'function call demo -{{Cl|CLOSE}} #1 -{{Cl|IF}} found% THEN {{Cl|PRINT}} "File exists!" {{Cl|ELSE}} {{Cl|PRINT}} "File not found!" -{{Cl|END}} - -{{Cl|FUNCTION}} Exist% (filename$) -f% = {{Cl|FREEFILE}} -{{Cl|OPEN}} filename$ {{Cl|FOR (file statement)|FOR}} {{Cl|APPEND}} {{Cl|AS}} #f% -{{Cl|IF}} {{Cl|LOF}}(f%) {{Cl|THEN}} Exist% = -1 {{Cl|ELSE}} Exist% = 0: {{Cl|CLOSE}} #f%: {{Cl|KILL}} filename$ -{{Cl|CLOSE}} #f% -{{Cl|END FUNCTION}} '' '' -{{CodeEnd}} -{{small|Code by Ted Weissgerber}} - - -''Example 3:'' When '''OPEN "SCRN:" FOR OUTPUT AS #f''' is used, '''PRINT #f''' will print the text to the screen instead of to a file: +''Example 2:'' When '''OPEN "SCRN:" FOR OUTPUT AS #f''' is used, '''PRINT #f''' will print the text to the screen instead of to a file: {{CodeStart}} '' '' f% = {{Cl|FREEFILE}} 'should always be 1 at program start {{Cl|OPEN}} "SCRN:" {{Cl|FOR...NEXT|FOR}} {{Cl|OUTPUT}} {{Cl|AS}} #f% @@ -153,15 +108,44 @@ g% = {{Cl|FREEFILE}} 'should always be 2 after 1 {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} 2 {{Cl|PRINT (file statement)|PRINT}} #i, "Hello World, Screen and File version" NEXT '' '' -{{CodeEnd}}{{small|GL implementation by Steve McNeill April 15, 2015}} +{{CodeEnd}}{{small|code by Steve McNeill}} : ''Note:'' Linux or Mac file names can use a path destination such as ".\SCRN:" to use SCRN: as an actual file name. -* '''QB64''' can use the [[_OPENCLIENT]], [[_OPENHOST]] or [[_OPENCONNECTION]] functions for TCP/IP internet connections. +''Example 3:'' Showcasing different file modes. +{{CodeStart}} +{{Cl|CLS}} + +{{Cl|OPEN}} "test.tst" {{Cl|FOR (file statement)|FOR}} {{Cl|OUTPUT}} {{Cl|AS}} #1 +{{Cl|PRINT (file statement)|PRINT}} #1, "If test.tst didn't exist:" +{{Cl|PRINT (file statement)|PRINT}} #1, "A new file was created named test.tst and then deleted." +{{Cl|PRINT (file statement)|PRINT}} #1, "If test.tst did exist:" +{{Cl|PRINT (file statement)|PRINT}} #1, "It was overwritten with this and deleted." +{{Cl|CLOSE}} #1 + +{{Cl|OPEN}} "test.tst" {{Cl|FOR (file statement)|FOR}} {{Cl|INPUT (file mode)|INPUT}} {{Cl|AS}} #1 +{{Cl|DO}} {{Cl|UNTIL}} {{Cl|EOF}}(1) +{{Cl|INPUT (file statement)|INPUT}} #1, a$ +{{Cl|PRINT}} a$ +{{Cl|LOOP}} +{{Cl|CLOSE}} #1 + +{{Cl|KILL}} "test.tst" + +{{Cl|END}} + +{{CodeEnd}} + +{{OutputStart}} +If test.tst didn't exist: +A new file was created named test.tst and then deleted. +If test.tst did exist: +It was overwritten with this and deleted. +{{OutputEnd}} +:'''Warning:''' Make sure you don't have a file named test.tst before you run this or it will be overwritten. - -''See also:'' +{{PageSeeAlso}} * [[PRINT (file statement)]], [[INPUT (file statement)]] * [[GET]], [[PUT]], [[WRITE (file statement)]] * [[INPUT$]], [[LINE INPUT (file statement)]] @@ -172,7 +156,6 @@ NEXT '' '' * [[_FILEEXISTS]], [[_DIREXISTS]] * [[_OPENCLIENT]], [[_OPENHOST]], [[_OPENCONNECTION]] {{text|(TCP/IP)}} * [[_SNDOPEN]], [[_LOADIMAGE]] -* [[Port Access Libraries]] {{text|(COM or LPT registers)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/OR_(boolean).txt b/internal/help/OR_(boolean).txt index 4929e2244..d1ee98b60 100644 --- a/internal/help/OR_(boolean).txt +++ b/internal/help/OR_(boolean).txt @@ -29,6 +29,7 @@ True ''See also:'' +* [[AND]], [[OR]] {{text|(logical operators)}} * [[AND (boolean)]], [[XOR (boolean)]] * [[IF...THEN]] diff --git a/internal/help/OUT.txt b/internal/help/OUT.txt index 0d708c342..31c2b0b3a 100644 --- a/internal/help/OUT.txt +++ b/internal/help/OUT.txt @@ -18,6 +18,7 @@ * Windows NT may block access to Parallel printer and Serial ports! See [[Port Access Libraries]] or other DLL's. * '''WARNING!''' Be sure that the address is useable. OUT accesses directly unlike [[POKE]] and '''can cause PC damage!''' * [[_PALETTECOLOR]] can also be used to set RGB intensity values using [[_RGB32|32 bit color]] values. +* OUT can toggle the blinking attribute of SCREEN 0 color 16-31 for legacy code. [[_BLINK]] is the preferred method. (starting with build 20170816/61). :::::::'''Color Port Palette access using OUT''' @@ -58,7 +59,15 @@ PRINT red%, green%, blue% '' '' :''Explanation:'' In [[SCREEN]] 0 this is one way to make high intensity background colors. [[COLOR]] ,15 is actually grey(7). -''Example 3:'' Restoring colors to a bitmap from the Red, Green and Blue [[BSAVE]]d indexed array of color values. +''Example 3:'' Toggling blinking colors in SCREEN beginning with build 20170816/61 +{{CodeStart}} '' '' +{{Cl|OUT}} &H3C0, &H10 'disables blinking and enables high intensity backgrounds (colors 16-31) +{{Cl|OUT}} &H3C0, 2 ^ 3 'reenables blinking and disables high intensity backgrounds (colors 16-31) +{{CodeEnd}} +: Note: For new code, the recommended practice is to use the new [[_BLINK]] {ON|OFF} statement. + + +''Example 4:'' Restoring colors to a bitmap from the Red, Green and Blue [[BSAVE]]d indexed array of color values. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 12 {{Cl|OUT}} {{Cl|&H}}3C8, 0 ' set color port for output at attribute 0 @@ -78,6 +87,7 @@ PRINT red%, green%, blue% '' '' * [[POKE]] {{text|(write to memory)}} * [[COLOR]], [[SCREEN]] * [[BSAVE]], [[BLOAD]] +* [[_BLINK]], [[_BLINK (function)]] * [[Port Access Libraries]] {{text|(COM or LPT registers)}} * [http://en.wikipedia.org/wiki/Input/output_base_address#Common_I.2FO_base_address_device_assignments_in_IBM_PC_compatible_computers PC I/O base address device assignments] diff --git a/internal/help/PAINT.txt b/internal/help/PAINT.txt index 9cb5f358e..20be9582a 100644 --- a/internal/help/PAINT.txt +++ b/internal/help/PAINT.txt @@ -1,8 +1,12 @@ The '''PAINT''' statement is used to color enclosed graphic objects with a designated fill color up to a border [[COLOR]]. -{{PageSyntax}} -: '''PAINT''' [{{KW|STEP}}] '''(''column%'', ''row%''), ''fillcolor'''''[, ''bordercolor%''][,''background$''] +Color {{PageSyntax}} +: '''PAINT''' [{{KW|STEP}}] '''(''column%'', ''row%''), ''fillcolor'''''[, ''bordercolor%''] + +Tiling {{PageSyntax}} +: '''PAINT''' [{{KW|STEP}}] '''(''column%'', ''row%''), ''background$'''''[, ''bordercolor%''] + {{Parameters}} @@ -12,7 +16,11 @@ The '''PAINT''' statement is used to color enclosed graphic objects with a desig :* [[INTEGER]] or [[LONG]] 32 bit ''Fillcolor'' is the color to paint the inside of an object. Colors limited to [[SCREEN]] mode used. :* A [[STRING]] paint argument has PAINT do "tiling," a process that paints a pattern rather than a solid color. * Optional [[INTEGER]] or [[LONG]] 32 bit ''border color'' is the color of the enclosed shape's border when different from the fill color. -* Optional ''background'' [[ASCII]] character sets the tiling style. Default = CHR$(0). Seldom used. +* Optional ''background'' [[ASCII]] character sets the tiling style. Omitted background Default is CHR$(0). + +::PAINT(x, y), CHR$(arg1) + CHR$(arg2)... + CHR$(argn) + +: Where the [[CHR$]] arguments are numerical values between 0 and 255, represented in binary form across the x column axis. ''Usage:'' @@ -20,6 +28,7 @@ The '''PAINT''' statement is used to color enclosed graphic objects with a desig * PAINT coordinates MUST be inside of a closed shape to be colored. Paint will not do anything when placed on the border color. * If the border color does not enclose the area, PAINT may flood the screen or go beyond the border area. * If the shape is not totally enclosed, every color except the border color may be painted over. + * [[DRAW]] shapes can be filled using the string "P ''fillcolor'', ''bordercolor''". Use a "B" blind move to offset from shape's border. @@ -74,6 +83,28 @@ drw$ = "C15S20R9D4R6U3R3D3R7U5H3U2R9D3G2D6F1D3F5L10D1G1L4H2L7G2L3H2L3U8L2U5 : ''Explanation:'' If the [[DRAW]] string is enclosed, the end values should each be 0! In the example, the proper result should be 4, 4 as there is a BF4 offset for PAINT which cannot be on a border. The result is 4, 5 because the shape is not completely enclosed. +''Example 3:'' Tiling using PAINT to create a red brick pattern inside a yellow border: +{{CodeStart}} +{{Cl|DIM}} Row$(1 {{Cl|TO}} 8) +{{Cl|SCREEN}} 12 + + 'make red-brick wall + Row$(1) = {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}FE) + {{Cl|CHR$}}({{Cl|&H}}FE) + Row$(2) = Row$(1) + Row$(3) = Row$(1) + Row$(4) = {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}0) + Row$(5) = {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}0) + {{Cl|CHR$}}({{Cl|&H}}EF) + {{Cl|CHR$}}({{Cl|&H}}EF) + Row$(6) = Row$(5) + Row$(7) = Row$(5) + Row$(8) = Row$(4) + Tile$ = Row$(1) + Row$(2) + Row$(3) + Row$(4) + Row$(5) + Row$(6) + Row$(7) + Row$(8) + + {{Cl|LINE}} (59, 124)-(581, 336), 14, B 'yellow box border to paint inside + {{Cl|PAINT}} (320, 240), Tile$, 14 'paints brick tiles within yellow border +{{CodeEnd}} + +<center>'''Tiling currently does not work in QB64!'''</center> + {{PageSeeAlso}} diff --git a/internal/help/PCOPY.txt b/internal/help/PCOPY.txt index 207f5607c..16c5a8b8f 100644 --- a/internal/help/PCOPY.txt +++ b/internal/help/PCOPY.txt @@ -13,7 +13,7 @@ The '''PCOPY''' graphics statement copies one source screen page to a destinatio * The working page is set as 0. All drawing occurs there. * The visible page is set as any page number that the SCREEN mode allows. * The [[_DISPLAY (function)]] return can be used a page number reference in '''QB64''' (See Example 1). -* The '''QB64''' [[_DISPLAY]] statement can also be used to stop screen flicker without page flipping or [[CLS]]. +* The '''QB64''' [[_DISPLAY]] statement can also be used to stop screen flicker without page flipping or [[CLS]] and '''is the recommended practice'''. ''Example 1:'' Creating a mouse cursor using a page number that '''you create''' in memory without setting up page flipping. diff --git a/internal/help/PEN.txt b/internal/help/PEN.txt index fcd1a84bb..febac8b68 100644 --- a/internal/help/PEN.txt +++ b/internal/help/PEN.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The '''PEN''' function returns requested information about the lightpen device used. @@ -8,7 +14,7 @@ The '''PEN''' function returns requested information about the lightpen device u ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * The lightpen was a device that detected the current position when the screen was drawn. It sends a signal when it is detected, from that the x and y coordinates of the pen relative to the screen is known. '''Seldom used today!''' (mainly because of the pain in the arm because of the constant lift of the pen to the screen and I suspect it left the screen rather dirty) diff --git a/internal/help/PEN_(statement).txt b/internal/help/PEN_(statement).txt index 57e41e768..b1f5a1631 100644 --- a/internal/help/PEN_(statement).txt +++ b/internal/help/PEN_(statement).txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The '''PEN''' statement enables/disables or suspends event trapping of the lightpen device which is seldom used today. @@ -6,7 +12,7 @@ The '''PEN''' statement enables/disables or suspends event trapping of the light ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * PEN [[ON]] - enables event trapping (automatically enabled with [[ON PEN]] though) * PEN [[OFF]] - disables event trapping. * PEN [[STOP]] - suspends event trapping (use PEN ON to enable it again). diff --git a/internal/help/PLAY(n).txt b/internal/help/PLAY(n).txt index efbc2ab18..efadd46ec 100644 --- a/internal/help/PLAY(n).txt +++ b/internal/help/PLAY(n).txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + '''PLAY(n)''' is a event-trapping function that returns the number of notes currently in the background music queue. @@ -6,7 +12,7 @@ ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * n can be any number and is only a dummy. * If the music is playing in foreground the function will return 0. diff --git a/internal/help/PRESET.txt b/internal/help/PRESET.txt index 881143990..ea58a1c14 100644 --- a/internal/help/PRESET.txt +++ b/internal/help/PRESET.txt @@ -2,13 +2,13 @@ The '''PRESET''' graphic [[SCREEN]] statement turns a pixel at a coordinate to t {{PageSyntax}} -:: '''PRESET''' [STEP]'''(''column%'', ''row%'')'''[, color_attribute] +:: '''PRESET''' [STEP]'''('''''column%'', ''row%''''')'''[, colorAttribute] ''[[Parameters]]:'' * Can use [[STEP]] when relative graphics coordinates are required. * ''column'' and ''row'' coordinates can be literal ot variable [[INTEGER]] values which can be offscreen. -* If the ''color attribute'' is omitted, a PRESET will be the background color, normally black. +* If the ''colorAttribute'' is omitted, PRESET will use the current [[_DEST|destination]] page's [[_BACKGROUNDCOLOR]]. ''Usage:'' @@ -16,7 +16,7 @@ The '''PRESET''' graphic [[SCREEN]] statement turns a pixel at a coordinate to t * Any color value other than 0 will be white in monochrome [[SCREEN]] modes 2 and 11 where the [[COLOR]] statement cannot be used. * PRESET can invisibly locate other graphics objects like [[CIRCLE]]s and add color to subsequent graphic objects and [[DRAW]] when used. * The PRESET action can be used in a graphics [[PUT (graphics statement)|PUT]] to produce a color inverted image on any background. See Example 2. -* The QB64 and QB graphic cursor is set to the center of the program window on program start. +* The graphic cursor is set to the center of the program window on program start for [[STEP]] relative coordinates. * '''PRESET can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only!''' @@ -30,7 +30,7 @@ SCREEN 12 -''Example 2:'' Displays the flags of countries that use simple horizontal or vertical color blocks using a highlighted arrow key selection menu. +''Example 2:'' Displays the flags of countries that use simple horizontal or vertical color blocks with a highlighted arrow key menu. {{CodeStart}} '' '' {{Cl|DIM}} {{Cl|SHARED}} c$(21), x$(21), gg%(477) diff --git a/internal/help/PRINT.txt b/internal/help/PRINT.txt index 963773482..4a16d511d 100644 --- a/internal/help/PRINT.txt +++ b/internal/help/PRINT.txt @@ -41,6 +41,7 @@ The {{KW|PRINT}} statement prints numeric or string expressions to the program s :* Use the [[_PRINTMODE (function)]] to find the current _PRINTMODE setting number. * [[WRITE]] can be used to print a list of comma separated data values to the screen with [[comma]]s between each value. * Use [[_DEST]] [[_CONSOLE]] before PRINT statements to be used in a [[$CONSOLE|console]] window. +* Use [[_CONTROLCHR]] '''OFF''' to PRINT the unprintable lower [[ASCII]] control characters in QB64. ''Example 1:'' Using semicolons, comma tabs or concatenation to insert [[ASCII]] characters and numbers in a PRINT: @@ -79,7 +80,8 @@ Hello city! * [[CSRLIN]], [[POS]], [[SCREEN (function)]] * [[COLOR]], [[LOCATE]], [[VIEW PRINT]] * [[INPUT]], [[STR$]], [[CHR$]] -* [[ASCII]] (character codes), [[Text Using Graphics]] (Demo) +* [[ASCII]] (character codes), [[_CONTROLCHR]] +* [[Text Using Graphics]] (Demo) {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/PRINT_(TCP%2FIP_statement).txt b/internal/help/PRINT_(TCP%2FIP_statement).txt index 30e3e0e76..7e025f655 100644 --- a/internal/help/PRINT_(TCP%2FIP_statement).txt +++ b/internal/help/PRINT_(TCP%2FIP_statement).txt @@ -10,6 +10,10 @@ The '''PRINT #''' statement sends QB64 formatted data to an open connection hand * Always check connections to handles before sending data. +''Availability:'' +* Version 0.954 and older. For version 1.000 and up use [[PUT (TCP/IP statement)]] + + :::::'''Communicating using QB64 Formatted messages:''' * Benefit: QB64 handles sending and receiving data in messages. It knows how long each message is and waits for the full message to arrive, avoiding partial messages which have been fragmented from being returned. diff --git a/internal/help/PSET.txt b/internal/help/PSET.txt index 1d2195339..34e5a18ae 100644 --- a/internal/help/PSET.txt +++ b/internal/help/PSET.txt @@ -2,20 +2,20 @@ The '''PSET''' grahics [[SCREEN (statement)|SCREEN]] statement sets a pixel to a {{PageSyntax}} -:: '''PSET''' [STEP]'''(''column%'', ''row%'')'''[, ''color_attribute''] +:: '''PSET''' [STEP]'''('''''column%'', ''row%''''')'''[, ''colorAttribute''] ''[[Parameters]]:'' * Can use [[STEP]] relative graphics coordinates from a previous graphic object. * ''Column'' and ''row'' can be literal or variable [[INTEGER]] coordinates values which can be offscreen. -* If the ''color attribute'' is omitted, PSET will adopt a color from a previous [[PRINT]] or graphics object's color. +* If the ''colorAttribute'' is omitted, PSET will use the current [[_DEST|destination]] page's _DEFAULTCOLOR. ''Usage:'' * ''Color attributes'' are limited to the SCREEN mode used. Any color value other than 0 will be white in [[SCREEN (statement)|SCREEN]]s 2 or 11. * PSET can locate other graphics objects and color [[DRAW]] statements. * The PSET action can be used in a graphics [[PUT (graphics statement)|PUT]] to produce an identical image on any background. -* The QB64 and QB graphic cursor is set to the center of the program window on program start. +* The graphic cursor is set to the center of the program window on program start for [[STEP]] relative coordinates. * '''PSET can be used in any graphic screen mode, but cannot be used in the default screen mode 0 as it is text only! (Or in any _NEWIMAGE(x, y, 0) screens which are text only as well.)''' diff --git a/internal/help/QB64_FAQ.txt b/internal/help/QB64_FAQ.txt index cfee7682e..47609705f 100644 --- a/internal/help/QB64_FAQ.txt +++ b/internal/help/QB64_FAQ.txt @@ -3,29 +3,29 @@ |} -As with everything else, this list will be updated to correspond to new progress of QB64 so make sure that you are using the latest version of '''QB64 (version 0.923 released 3/12/10)'''. Please note that it may take a short time to update this list. +As with everything else, this list will be updated to correspond to new progress of QB64 so make sure that you are using the latest version of '''QB64 (version 1.1 released in 1/20/17)'''. Please note that it may take a short time to update this list. -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +<center>'''You may need Administrator rights to install or use QB64!'''</center> -<center>'''{{text|It's a good idea to exclude "QB64.exe" from any real-time anti-virus scanning to prevent IDE Module Errors!|red}}'''</center> +<center>'''{{text|It's a good idea to exclude "QB64.exe" (also the internal folder) from any real-time anti-virus scanning to prevent IDE Module Errors!|red}}'''</center> ==Q: What is QB64?== -A: '''QB64''' is a BASIC compatible Editor and C++ compiler that creates working Executable files from Qbasic BAS files that can be run on 32 or 64 bit PC's using '''WINDOWS'''(XP, Vista and newer), '''LINUX''' or '''MAC'''(OSX only). The goal is to be 100% compatible with QuickBasic 4.5 plus add hundreds of new abilities such as program icons and custom sized windows and a great [[IDE|Editor]] with a new Help Menu. +A: '''QB64''' is a BASIC compatible Editor and C++ compiler that creates working Executable files from Qbasic BAS files that can be run on 32 or 64 bit PC's using '''WINDOWS'''(XP, Vista and newer), '''LINUX''' or '''macOS'''. The goal is to be 100% compatible with QuickBasic 4.5 plus add hundreds of new abilities such as program icons and custom sized windows and a great [[IDE|Editor]] with a new Help Menu. The '''new keywords''' add some '''new features''' such as playing '''music or sound''' files and instant access to '''32 bit graphics''' file images. Also '''TCP/IP''' internet communication is available to '''download''' files, '''email''' messages over the web or play '''internet games'''. '''DLL Libraries''' can add more programming options and QB64 can access all of the new USB gaming '''controllers''' and '''printers'''. -QB is an abbreviation for '''QBasic''' or '''QuickBASIC''' which is an easy to learn language that grew very popular in the 90's. It uses simple syntax but holds great potential as there are methods to achieve nearly anything. '''Qbasic is NOT DEAD thanks to QB64!''' +QB is an abbreviation for '''QBasic''' or '''QuickBASIC''' which is an easy to learn language that grew very popular in the 90's. It uses simple syntax but holds great potential as there are methods to achieve nearly anything. '''QBasic is NOT DEAD thanks to QB64!''' <p style="text-align: center">[[Keywords currently not supported by QB64]]</p> -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +<center>'''You may need Administrator rights to install or use QB64!'''</center> ==Q: Does it have modern features? Do they HAVE to be used?== @@ -40,7 +40,7 @@ You could code using the original QuickBASIC syntax all the way through and it s <center>'''Some members can still run QB4.5 programs so we can test problem code!'''</center> -<center>QB 4.5 code only! QB64 was not meant to run PDS(7.1) QBX code. Will run most GW Basic code too!</center> +<center>QB 4.5 code only! QB64 was not meant to run PDS (7.1) QBX code. Will run most GW Basic code too!</center> <center>'''If your program(s) don't work correctly(check your code first) please feel free to post in the "Discussion" board.'''</center> @@ -51,7 +51,7 @@ Galleon is constantly working on pure compatibility. You don't have to set it up <center>'''QB64 FEATURES INCLUDE...'''</center> {{TextStart}} - 1) Full graphic functions for [[_NEWIMAGE|images]] up to 32 bit color. [[_ALPHA|Alpha]] transparancies supported. + 1) Full graphic functions for [[_NEWIMAGE|images]] up to 32 bit color. [[_ALPHA|Alpha]] transparency supported. 2) Instant [[_LOADIMAGE|loading]] of image files including BMP, PNG, JPEG, GIF and more... @@ -67,65 +67,60 @@ Galleon is constantly working on pure compatibility. You don't have to set it up 8) Integrated [[_MOUSEINPUT|mouse]] and [[_DEVICES|game controller]] input including [[_MOUSEWHEEL|scroll wheel]] support. - 9) Support for C++, SDL, Windows API and other custom Dynamic Link [[Libraries]]. + 9) Support for C++, OpenGL, Windows API and other custom Dynamic Link [[Libraries]]. {{TextEnd}} -<p style="text-align: center"> [http://dl.dropbox.com/u/8440706/Graphics%20Demo.zip Graphics Demo Download].</p> - - <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> -==Q: How do I install QB64 on Windows, Linux, Mac OSX or run programs in Android?== +==Q: How do I install QB64 on Windows, Linux, macOS or run programs in Android?== -A: Since this is a relatively new project, it hasn't been tested as thoroughly as to have defined specifications. However, if you have a relatively new computer you will probably be fine. QB64 supports the following Operating Systems in one download: +A: If you have a relatively new computer you will probably be fine. QB64 supports the following Operating Systems in one download: -<center>'''Windows NT(XP), Windows Vista and Windows 7'''</center> +<center>'''Windows NT(XP), Windows Vista, Windows 7, 8 or 10:'''</center> :'''1)''' Click the following link and Windows box to download QB64: [http://www.qb64.net QB64 Windows Downloads] :'''2)''' Unzip to any folder path you wish. The ZIP file will create a ''QB64'' folder for the program files. -:* Executable programs are portable between like systems by copying the executable file as well as the QB64 DLL files. -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +:* Executable programs are portable between like systems by copying the stand-alone executable file. +:* ''Versions of QB64 prior to 1.000 require that your binary is distributed with the DLL files that came bundled.'' +<center>'''You may need Administrator rights to install or use QB64.'''</center> <center>'''Windows 2000 running QB64 versions .94 and Above'''</center> -: QB64 version .940 and above now contain a full version of the Ming Compiler! This may create an entry point error in Windows 2K. +: QB64 version .940 and above contain a full version of the Ming Compiler! This may create an entry point error in Windows 2K. :'''1)''' Click the following link and Windows box to download QB64: [http://www.qb64.net QB64 Windows Downloads] :'''2)''' Unzip to any folder path you wish. The ZIP file will create a ''QB64'' folder for the program files. Check for ''MSVCRT.DLL'' errors! -:'''3)''' If there is an error, unzip the contents of the ZIP FIX file into the QB64 folder after Qb64 has updated to the latest version. +:'''3)''' If there is an error, unzip the contents of the ZIP FIX file into the QB64 folder after QB64 has updated to the latest version. <center>[http://www.qbasicnews.com/dav/files/qb64v942-win2k-fix.zip Download ZIP FIX for Windows 2000 if QB64 does not run correctly!]</center> <center>This download fix will be updated when necessary by Dav</center> ---- -<center>'''Certain versions of LINUX 32 and 64 bit'''</center> +<center>'''Most versions of LINUX 32 and 64 bit'''</center> :'''1)''' Click on the following link and Linux box to download QB64: [http://www.qb64.net QB64 Linux Downloads] -:'''2)''' libsdl packages (dev and non-dev)(libsdl, libsdl-image, libsdl-mixer, libsdl-net, libsdl-ttf ) and GCC compiler must be installed. -:'''3)''' After extracting ''qb64v0??-lnx64.tar.gz'' run the installation batch/script called ''setup.sh'' in the main ''qb64'' folder to setup QB64. +:'''2)''' You will need the following installed: OpenGL developement libraries, ALSA development libraries, GNU C++ Compiler (g++) +:'''3)''' After extracting the downloaded package, run the installation batch/script called ''setup_lnx.sh'' in the main ''qb64'' folder to setup QB64. +:'''4)''' It is not advisable to install QB64 as root. <center>Executable programs are portable between like systems by copying the executable file.</center> <center>'''The Linux 32bit & 64bit versions are combined as of the v 0.925 update'''</center> -<center>'''Note: Some QB64 keywords and procedures are not available as of this Linux release.'''</center> - - -<center>[[Puppy Linux Installation]]</center> +<center>'''Note: Some QB64 keywords and procedures are not available as of this Linux release.'''</center> <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> ---- -<center>'''MAC OSX 32 and 64 bit only'''</center> -:'''1)''' You MUST install '''Apple's Xcode package''' for C++ compilation from their website: [http://developer.apple.com/technologies/tools/xcode.html Xcode.html download] +<center>'''macOS'''</center> +:'''1)''' You MUST install '''Xcode command line tools''' for C++ compilation from their website. In a terminal window, type the following command: '''xcode-select --install''' (more info here: [http://developer.apple.com/technologies/tools/xcode.html Xcode download]) :     (you won't be using the Xcode interface, QB64 just needs to have access to the C++ compiler it installs) -:'''2)''' If you have a '''32-bit''' MacOSX system, you should copy: ''qb64\common\libfreetype_alternatives\tiger_32bit\libfreetype.6.3.dylib''     over ''qb64\common\libfreetype.6.dylib'' if you are having difficulties. IE: Rename ''libfreetype.6.3.dylib'' to ''libfreetype.6.dylib'' -:'''3)''' Click on the following link and MAC OSX box to download QB64 for MacOSX: [http://www.qb64.net QB64 MAC OSX Downloads] -:     Extract the ''MACOSX.zip'' file and run ''setup.command'', found within the QB64 folder to install the QB64 compiler. +:'''3)''' Click on the following link and MAC OSX box to download QB64 for macOS: [http://www.qb64.net QB64 MAC OSX Downloads] +:     Extract the downloaded package and run ''setup_osx.command'', found within the QB64 folder to install the QB64 compiler. -<center>'''After installation you should run QB64_start.command to run qb64.'''</center> +<center>'''After installation you should run '''qb64_start_osx.command''' to run qb64.'''</center> -:* Executable programs are portable between like OSX systems by copying the executable file as well as the ''common'' folder. +:* Executable programs are portable between like OSX systems by copying the executable file. :* To help launch executables without a console, a file called ''programname_start.command'' is created along with the program. <center>'''Note: Some QB64 keywords and procedures are not available as of this MAC release.'''</center> @@ -134,28 +129,38 @@ A: Since this is a relatively new project, it hasn't been tested as thoroughly a ---- -<center>'''Coming soon! Run QB64 program on Android Devices!'''</center> - - -<center>'''[http://www.qb64.net/ Downloads and required programs for using QB64 programs on Android devices]'''</center> - - -<center>'''More information to follow in coming months!'''</center> - +<center>'''References to Android in QB64 refer to the Android Experiment. More information here: [http://www.qb64.net/forum/index.php?topic=13162.0 Android QB64] (may be outdated/non-functional)'''</center> <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> +==Q:The setup scripts don't work in Linux and macOS. How can I fix them?== +A: If you have problems running the install scripts under Linux (./setup_lnx.sh) or macOS (./setup_osx.command), run the following line in terminal, from your QB64 folder: + +===Linux=== +* <nowiki>find . -name '*.sh' -exec sed -i "s/\r//g" {} \;</nowiki> + +===macOS=== +* <nowiki>find . -name '*.command' -exec perl -pi -e 's/\r\n|\n|\r/\n/g' {} \;</nowiki> +* Don't forget you need to have Xcode command line utilites installed to use QB64. + +If you have any other issues, check out the Forum: + +* [http://www.qb64.net/forum/ QB64 Forum] +* [http://www.qb64.net/forum/index.php?topic=13359.msg115525#msg115525 Fixing setup scripts] ==Q: How do I upgrade the 32 bit Windows version of QB64 to 64 bit functionality?== A: The process has been simplified a lot recently. -First, download a fresh QB64 version. (I'd recommend the latest dirty build.) -Then download a x64 version of the min-gw compiler. -Delete the 32-bit compiler from internal/c/compiler and replace with the 64-bit version. -Run the setup_win.bat file (you may need to move it to the root QB64 folder for it to work). - -'''<center>That's it. You now have a x64 version of QB64 and x64 will be indicated in the QB64 title bar.</center>''' +# Download the version of QB64 which you want to transform into a 64-bit version from THE QB64 OFFICIAL WEBSITE. +# Grab a pre-edited copy of the 64-bit mingw compiler. You can find it here, [https://www.dropbox.com/s/gapnz7m22yc0mlv/QB64%2064-bit%20mingw%20compiler%20%2808-01-2017%29%20PRE-EDITED.7z?dl=0 QB64 64-bit mingw compiler (08-01-2017) PRE-EDITED], stored permanently in [[User:SMcNeill |Steve McNeill]]'s Dropbox account. +# Extract the QB64 file wherever you want it to be on your system. +# Go into the folder where you installed QB64 and head to the '''internal/c/c_compiler''' folder. +# Delete everyone of those files and folders. +# Extract the mingw 64-bit compiler into that folder. You're looking to replace the old contents with the new contents. Watch for nesting a folder inside a folder by accident. +# Go into the main QB64 directory, look for setup_win.bat. If it's not there, grab the download for it from below and put it into the main folder. (I don't think the archives at qb64.net has the file included in it, though if you download from the repo directly, you can find it. It's kind of a developer tool, moreso than something an user needs cluttering up their directory structure.) +# Run that setup_win.bat file. If everything is extracted to the proper places, you should build and have a version of QB64 open up where the title screen now reads "QB64x64". Congrats!! You now have a working, 64-bit version of QB64. +That's all it takes! {{small|Tip courtesy of Steve McNeill}} @@ -163,11 +168,11 @@ Run the setup_win.bat file (you may need to move it to the root QB64 folder for <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> ==Q: Why won't QB64 work on my computer?== -QB64 currently supports Windows versions from XP to the latest version. Most Linux and MAC OSX versions are also supported. +QB64 currently supports Windows versions from XP to the latest version. Most Linux and macOS versions are also supported. -<center>'''Don't move QB64 executable or libraries out of the QB64 folder! The various sub-folders hold the C++ compiler files!'''</center> -<center>The DLL files may be copied into the Windows ''System32'' or ''SysWOW64'' folder for program access outside of the QB64 folder. They can also be placed in a separate folder or download package with the EXE and program files.</center> +<center>'''Don't move QB64 executable out of the QB64 folder! The various sub-folders hold the C++ compiler files!'''</center> +<center>Versions of QB64 prior to 1.000 require the accompanying DLL files, which may be copied into the Windows ''System32'' or ''SysWOW64'' folder for program access outside of the QB64 folder. They can also be placed in a separate folder or download package with the EXE and program files.</center> Does your Windows system have another version of the '''MinGW''' compiler? Does it have '''Fortran''' or '''GFortran'''? You can check your environmental values using the following batch file which will create the '''''settings.inf''''' text file in the batch folder: @@ -209,7 +214,7 @@ TMP=C:\DOCUME~1\User1\LOCALS~1\Temp <center>Environmental values to check and possibly clear are '''PATH=''', '''LIBRARY_PATH=''', '''LIB=''' or '''CPLUS_INCLUDE_PATH='''</center> -<center>'''QB64 does NOT alter computer settings! Required files, libraries and the compiler are organized in the QB64 folder.'''</center> +<center>'''QB64 does NOT alter computer settings! All required files are organized in the QB64 folder.'''</center> : Try to run the following '''''TestQB64.bat''''' batch file from the QB64 folder only: @@ -269,7 +274,7 @@ QB64 can be fast when you need it to be, but take the time to consider the impac ==Q: Why won't my QB64 compiled programs run in folders other than the QB64 folder?== -A: QB64 requires certain DLL files to be in the program folder or in the Windows system path. +A: Versions of QB64 prior to 1.000 required certain DLL files to be in the program folder or in the Windows system path. <center>{{Text|C:\WINDOWS\SYSTEM32|green}}</center> @@ -281,16 +286,16 @@ Copy each of the DLL files included with QB64 to the System32 or [[SysWOW64]] fo <center>[http://www.samlogic.net/articles/32-64-bit-windows-folder-x86-syswow64.htm SysWOW64 and Program Files(x86) folders on 64 bit Windows OS.]</center> -<center>'''[[QB64_FAQ#Q:_What_files_are_required_to_run_QB64_SDL_programs_in_Windows.3F|List of required QB64 DLL files]]'''</center> - - -<center>Mac OSX and Linux may require other files to be included with your program!</center> +<center>'''[[QB64_FAQ#Q:_What_files_are_required_to_run_QB64_SDL_programs_in_Windows.3F|List of required QB64 DLL files for older versions (prior to 1.000)]]'''</center> <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> ==Q: How do I find the current QB64 program path in Windows or Linux?== +* With the [[_CWD$]] and [[_STARTDIR$]] commands you can get the current working path and the path from which your program was started, respectively. For older versions of QB64 in which these statements may not be available, use the procedures below. + + :'''Windows path:''' {{CodeStart}} '' '' {{Cl|PRINT}} PATH$ @@ -359,7 +364,7 @@ path$ = directory$ ==Q: How do I update the information in QB64 HELP?== -A: Use the '''Update current page''' in the [[IDE]] Help menu selection to update a page. Use the '''Update all pages''' choice to update them all, but this may take longer. In general you may want to update monthly or a week after a new version release. +A: The help provided in the QB64 IDE Help System fetches the pages from this wiki. Use the '''Update current page''' in the [[IDE]] Help menu selection to update a page. Use the '''Update all pages''' choice to update them all, but this may take longer. In general you may want to update monthly or a week after a new version release. <center>[http://qb64.net/wiki/index.php?title=IDE#Help_Menu_.28Alt_.2B_H.29 QB64 IDE Help Menu]</center> @@ -368,16 +373,18 @@ A: Use the '''Update current page''' in the [[IDE]] Help menu selection to updat A: If the libraries are pure QB 4.5 code then yes, otherwise no. QLB files are not supported but you can easily copy your favorite SUBs or FUNCTIONs to a text BI file and [[$INCLUDE]] them at the end of ANY program. Include them AFTER all SUB and FUNCTION code in the BAS file! -As of Dec 3, 2010 QB64 acquired [[DECLARE LIBRARY]] to allow users to reference C, Windows, SDL and other DLL libraries. If you find some functions that you like please share them with us at the forum! The following pages list working functions our members have found and tested: +As of Dec 3, 2010 QB64 acquired [[DECLARE LIBRARY]] to allow users to reference C, Windows, OpenGL and other DLL libraries. If you find some functions that you like please share them with us at the forum! The following pages list working functions our members have found and tested: -<center>[[C Libraries]], [[SDL Libraries]], [[DLL Libraries]], [[Windows Libraries]]</center> +<center>[[C Libraries]], [[DLL Libraries]], [[Windows Libraries]]</center> +*[[SDL Libraries]] ''(obsolete since version 1.000 - available here for historic purposes) + <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> ==Q: I can't get my QB 4.5 sourcecode to work in QB64! Why?== -A: Perhaps that is because QB64 isn't 100% compatible yet, it is a work in progress. It is around 95-98% compatible right now, and that is a large number! As QB64 approaches the 1.0 version it approaches 100%. Look at the [http://www.qb64.net/forum/index.php?board=15.0 Unimplemented Qbasic Commands Forum] for statements that are currently not available. +A: Perhaps that is because QB64 isn't 100% compatible yet, it is a work in progress. It is around 95-98% compatible right now, and that is a large number! The commands that haven't been implemented are either obsolete or are too obscure and have been replaced by modern functionality. Look at the [http://www.qb64.net/forum/index.php?board=15.0 Unimplemented Qbasic Commands Forum] for statements that are not available. <p style="text-align: center">[[Keywords currently not supported by QB64]]</p> @@ -386,17 +393,13 @@ A: Perhaps that is because QB64 isn't 100% compatible yet, it is a work in progr '''Compiler errors''' are another subject. Always try to test the program in Qbasic BEFORE trying to run or compile it in QB64! You may find '''syntax or other code errors''' that the QB64 IDE may not find yet as a bonus! Always check the code before blaming QB64! -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +<center>'''You may need Administrator rights to install or use QB64.'''</center> <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> -==Q: What files are required to run my QB64 GL compiled program in my Operating System?== -A: QB64 GL uses DLL information internally so no external GL DLL files are required to be with your program EXE file. The GL version also only loads the required libraries for your code. - - -<center>'''Programs must load image, sound and data files when required by your program!'''</center> - +==Q: What files are required to run my QB64 compiled program in my Operating System?== +A: Programs compiled by QB64 (version 1.000 and up) are stand-alone so no external OpenGL DLL files are required to be with your program EXE file. <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> @@ -478,23 +481,15 @@ You can use ANY of the ASCII characters to add borders, arrows, and many other c ==Q: MUST I copy or drag ALL of my program files to the QB64 folder?== -A: NO! But you will not be able to compile or run it using the editor either. The editor requires that the files associated with your program be available when the program starts AFTER the EXE has been created! You can compile your program without using the editor however. It will require you to do a few extra things: -{{TextStart}} - - 1) Use a batch file or a command line as follows: QB64 -c ''yourfile.BAS'' - - 2) Move the compiled EXE file back to the folder with the program files. - - 3) Copy ALL of the QB64 DLL files from the QB64 folder to your new program's folder. - - 4) Try the EXE file to see how it works. - -{{TextEnd}} - -<center>'''A download is available that can make transferring the required library files easily. Just unzip to any folder!'''</center> +A: You can instruct QB64 to save the resulting executable file to the same folder as your source code file so that all your project files can reside in a separate folder, for better organization. In the [[IDE]] of versions 1.000 and up, go to the Run menu and tick the option "Save EXE in the source folder". This way, next time you hit F5, Ctrl+F5 or even F11, QB64 will compile your .BAS file and the .EXE will be placed in the same folder. -<p style="text-align: center"> [http://bit.ly/MZ9Jhu QB64 Program Package ZIP file].</p> +For older versions of QB64, you can use a batch file, as instructed below: + +# Use a batch file or a command line as follows: QB64 -c ''yourfile.BAS'' +# Move the compiled EXE file back to the folder with the program files. +# Copy ALL of the QB64 DLL files from the QB64 folder to your new program's folder. +# Try the EXE file to see how it works. <center>'''The Answer to the Question below will show you how to create a batch file and compile BAS files from ANY location.'''</center> @@ -504,13 +499,14 @@ A: NO! But you will not be able to compile or run it using the editor either. Th ==Q: Is there a way to use the compiler without running my program or using the IDE?== A: Yes! No other program files besides the BAS file are required! Use the following command to compile a program without running it: -{{WhiteStart}} - ''QB64 -c ''yourfile.BAS'' -{{WhiteEnd}} -One advantage to compiling without running a program is that the QB64 editor will require that ALL of the necessary program files be placed inside of the QB64 folder or errors will occur when it is run! Also the EXE file will not be made or will '''disappear''' as it is no longer a valid application! To run the newly created EXE file, MOVE IT BACK to the location where your other program files reside. -<center>'''NOTE: You must also copy the QB64 DLL libraries to the new program's folder location or the System folder!'''</center> +* '''QB64 -c yourfile.BAS''' +* '''QB64 -x yourfile.BAS''' ''(compiles using the console only)'' +* '''QB64 -c yourfile.BAS -o destination_path\destination executable_name.exe''' ''(compiles the .BAS file and outputs the executable to a separate folder)'' + + +''NOTE: Versions of QB64 prior to 1.000 require that the DLL libraries are copied along with your executable or installed in the System folder (Windows).'' The batch file below can compile any BAS file from any location using drag and drop. The EXE will be created in the QB64 folder: @@ -531,9 +527,6 @@ cmd /c start /low QB64.exe -c %1 '' '' -<center>[http://bit.ly/Oa6Ha0 Download the QB64 Editor and Compiler Shortcuts and Compile Error Batch Files]</center> - - <center> '''Associating the batch file in the Right Click Open With pop-up menu'''</center> You can associate the batch file to the Right Click Popup Menu's ''Open With'' dialogue choices when you right click ANY BAS file: @@ -548,7 +541,7 @@ You can associate the batch file to the Right Click Popup Menu's ''Open With'' d <center>The compiled EXE file can be found in the QB64 folder!</center> -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +<center>'''You may need Administrator rights to install or use QB64.'''</center> <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> @@ -585,31 +578,19 @@ A: CHAIN has been implemented in QB64 versions 0.851 up. Be sure to download the The statement also can use [[COMMON]] or [[COMMON SHARED]] to pass program information. However QB64 uses files to pass the information. If your program moves to a location other than the EXE file's location, the file may be inaccessable! To avoid this problem, make sure that your program can refer to that location using a path. -There are minor differences from QBasic in that it doesn't open a program in the same window and does not retain the previous screen mode or format. This problem will be addressed in future releases! +There are minor differences from QBasic in that it doesn't open a program in the same window and does not retain the previous screen mode or format. <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> ==Q: Some screens look small. Can I enlarge them or make them fullscreen?== -<center>You can use the [[_FULLSCREEN]] statement to make your programs run fullscreen. - - -You can also create custom sized screens with page flipping and up to 32 bit colors using [[_NEWIMAGE]]. - - -Page flipping is available in most screens and the new [[_DISPLAY]] feature allows the images to be displayed when YOU desire. - - -Picture or image files such as BMP, PNG, JPEG and GIF are EASY to load using [[_LOADIMAGE]]. - - -Once images are loaded, all you have to do is use the image handle with any of the new statements and functions. - - -[[_PUTIMAGE]] GETs and PUTs images fast in ONE call. It can even stretch or compress the image sizes!</center> - - -<p style="text-align: center"> [http://dl.dropbox.com/u/8440706/Graphics%20Demo.zip Graphics Demo Download].</p> +* You can use the [[_FULLSCREEN]] statement to make your programs run fullscreen. +* [[$RESIZE]] can be added to a program so you can track window resize events. (version 1.000 and up) +* You can also create custom sized screens with page flipping and up to 32 bit colors using [[_NEWIMAGE]]. +* Page flipping is available in most screens and the new [[_DISPLAY]] feature allows the images to be displayed when YOU desire. +* Picture or image files such as BMP, PNG, JPEG and GIF are EASY to load using [[_LOADIMAGE]]. +* Once images are loaded, all you have to do is use the image handle with any of the new statements and functions. +* [[_PUTIMAGE]] GETs and PUTs images fast in ONE call. It can even stretch or compress the image sizes! <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> @@ -622,9 +603,9 @@ A: Yes, they are emulated to use the soundcard instead of the old boring monoton Capabilities include: -* 1) Multiple sound tracks -* 2) Volume and speaker control -* 3) Background music +# Multiple sound tracks +# Volume and speaker control +# Background music <center>'''SOUND HAS RETURNED TO QBASIC!'''</center> @@ -655,18 +636,17 @@ A: Yes, program windows can be moved to them automatically using [[_SCREENMOVE]] ==Q: Why isn't the [[IDE]] always working as I would expect?== -A: The [[IDE]] is currently being worked on, but it has a lower priority than the compiler (for obvious reasons), syntax checking isn't always working as you would expect, etc., Galleon knows about these issues and makes effort to resolve them in due time. The compiler is priority number one though and the [[IDE]] will be improved as warranted. +A: The [[IDE]] has many features shared with modern IDEs while retaining the retro look reminiscent of QuickBasic 4.5 and QBasic. You may request new features in the Discussion subforum and they will be analyzed for implementation, although no warranty of being added is made. -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +You can also use QB64 as a compiler only, so that you can choose any alternate editor of your choice. + +<center>'''You may need Administrator rights to install or use QB64'''</center> <center>'''Alternate Editors:''' [[PSPAD|PSPad Editor for Windows]] and [[GEDIT|Gedit Editor for Linux]]'''</center> -<center>[http://www.qb64.net/forum/index.php?board=3.0 Report Compiler Bugs here!] - - -[http://www.qb64.net/forum/index.php?board=21.0 Report missed Syntax Errors here!]</center> +<center>[http://www.qb64.net/forum/index.php?board=21.0 Report missed Syntax Errors here!]</center> <center>'''[[Known QB64 Issues]]'''</center> @@ -674,7 +654,6 @@ A: The [[IDE]] is currently being worked on, but it has a lower priority than th <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> - ==Q: If QB64 creates Basic programs why is there no Immediate Window?== @@ -683,7 +662,7 @@ A: Because there is no '''QB64''' interpreter. All C code has to be compiled bef '''QB64''' uses the Immediate window area to suggest syntax for keyword entries and give the compiler status when compiling. To run code snippets or do program calculations using QB64 just open up another instance of the [[IDE]]. Each new instance of QB64 will create a new numbered instance of Untitled(n).exe when compiled. If you want to save the test code for later use, Save it as a BAS file name before closing that instance of QB64. Ihe [[IDE]] will always ask if you want to save new or edited code. -Qbasic and Quickbasic allowed BAS programs to be run in an interpreter to test the code. The '''Run''' Menu will allows the following: +Qbasic and Quickbasic allowed BAS programs to be run in an interpreter to test the code. The '''Run''' Menu in QB64 allows the following: {{TextStart}}'''{{text|S|white}}tart F5''' Compiles into EXE file and runs program(with code whiteout). ─────────────────────────── @@ -699,7 +678,7 @@ Qbasic and Quickbasic allowed BAS programs to be run in an interpreter to test t <center>'''Associated text [[$INCLUDE]] code files, [[DECLARE LIBRARY|LIBRARY]] DLL files and C++ ''.h'' header files must be in the QB64 folder to compile.''' -Only the associated DLL files need to be included with the program ''EXE'' after it is compiled. +In QB64 versions prior to 1.000 the provided DLL files need to be included with the program ''EXE'' after it is compiled. (The compiler can find Windows DLL files in the System folder and C++ DLL files in the QB64 folder.) @@ -725,18 +704,18 @@ Use [[SLEEP]] or [[INPUT$]] to wait for user entries, key presses or menu select ==Q: Can I resize the QB64 Editor([[IDE]])? == -A: Yes, use the ''Alt + Enter'' key combination to switch from windowed to full screen mode. This can also be used to resize a QB64 program screen! +A: Yes, drag the window border to resize it or use the ''Alt + Enter'' key combination to switch from windowed to full screen mode. This can also be used to resize a QB64 program screen (see [[$RESIZE]]). There is also a way to set the window size in the ''Options'' Menu. Select ''Display'' and change the size from 80 columns and 25 rows to a '''larger''' size. The size '''cannot be less than 80 by 25!''' The size denotes the TEXT column and rows only! DO NOT MAKE IT TOO LARGE! -If there is ever a problem with an OPTION that you set, just Delete the '''.\internal\temp\options.bin''' file. Then restart QB64. You can find the program listed in the taskbar. Right click and select ''Close'' from the pop-up menu. +If there is ever a problem with an OPTION that you set, just Delete the '''.\internal\temp\options.txt''' file. Then restart QB64. You can find the program listed in the taskbar. Right click and select ''Close'' from the pop-up menu. <center>'''See the [[IDE|IDE Page]] for more information.'''</center> ==Q: The autoformatting doesn't work correctly in the [[IDE]]...== -A: The autoformatting only has minor bugs which doesn't alter the actual execution of the code in any way, for now if you save your code in the current formatting it will format correctly in later versions of QB64. If the code you have is 'corrupted' by autoformatting, then please report it on the forums, because that would be a serious issue, if you can you should also provide code example of how it was corrupted. +A: The autoformatting feature allows you to set a fixed number of spaces to indent your code. You can also choose to have keywords automatically changed to UPPERCASE as well as indenting the contents inside SUB/FUNCTION procedures. If you don't like the way it alters your code (both at load time and as you type it), just disable it. <center>'''Autoformatting and Updating can be turned off in the [[IDE]] using the [[IDE#Options_Menu_.28Alt_.2B_O.29:|Options Menu]]!</center> @@ -744,15 +723,10 @@ A: The autoformatting only has minor bugs which doesn't alter the actual executi ==Q: Does it work on Windows 98 or any OS older than Windows 2000?== -A: No, not yet, it is a low-priority issue, since QB64 is made to run on new systems (WinXP -> Vista etc.), Galleon has said that he wants to make it work on Windows 98 too, so if you are patient it will eventually work there as well. It should work on NT, XP, 2000, Vista and Windows 7 using 32 or 64 bit systems. The .exe files produced by QB64 do work in Windows 98 as long as the QB64 DLL libraries are supported on that system. - - -<center>'''QB64 also has versions for Linux and Mac OSX operating systems!'''</center> - +A: No, it doesn't. QB64 is made to run on new systems (WinXP and up, Linux and macOS). The .exe files produced by QB64 should work in Windows 98 as long as the required DLL libraries, if any, are supported on that system. <center>'''See the [[IDE|IDE Page]] for more information.'''</center> - ==Q: Can Line Numbers be removed from older program code?== A: Yes, you can use the Microsoft program below or the program on the following page to remove line numbers that are not required by Basic keywords such as [[GOTO]]. See: [[Line number|Removing line numbers]] @@ -777,11 +751,14 @@ A: Not directly, but [[_FLOAT]] currency values up to 4 decimal places can be mu <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> -==Q: What files are required to run QB64 SDL programs in Windows?== -A: The QB64 compiler and '''EVERY''' EXE file created by the compiler are dependant on various DLL Library files to function properly. These files are found inside of the QB64 folder. This also explains why QB64 will create ALL EXE files in the QB64 folder no matter where the original BAS file is located on the computer. Your new program will require these files too, but you can move the DLL files to your shared SYSTEM32 folder to eliminate duplicates! '''Note:''' As of version 0.94(9/8/2011), QB64 now includes the full GCC compiler. +==Q: What files are required to run older QB64 programs (version .954 and older) in Windows?== +A: Older versions of the QB64 compiler (.954 or older) and '''EVERY''' EXE file created by this version of the compiler are dependant on various DLL Library files to function properly. These files are found inside of the QB64 folder. This also explains why QB64 will create ALL EXE files in the QB64 folder no matter where the original BAS file is located on the computer. Your new program will require these files too, but you can move the DLL files to your shared SYSTEM32 folder to eliminate duplicates! -<center>'''YOUR WINDOWS COMPILED SDL EXE FILE NEEDS THESE QB64 DLL FILES TO RUN!'''</center> +'''Note:''' QB64 produces stand-alone executable files from version 1.000 onward. + + +<center>'''Files required for executables created by older versions of QB64:'''</center> <center>''The list of library files you need to include with your program(s) as of July 2010:''</center> @@ -813,17 +790,8 @@ libvorbisfile-3.dll SDL.dll SDL_image.dll SDL_mi {{WhiteEnd}} This will allow all of your programs to run in any location without copies of the DLL files inside of every program folder. Administrator rights may be necessary to move them there! The '''DATA''' folder files are integrated into the compiler itself in versions .91 and above. -'''If you plan to make your program available for download, the DLL files listed above must be included with the program.''' - -<center>A ZIP file with all of the required files can be downloaded here:</center> - -<p style="text-align: center"> [http://bit.ly/MZ9Jhu QB64 Program Package ZIP file].</p> - - -The ZIP file can be used to unzip the DLL libraries into any program's folder location. It can also be used to create program download packages. Just create a folder with all of the relevant program files needed by your program and unzip the required QB64 files into it. Then you can ZIP the folder or all of the folder contents into your own zip program packages. We hope to have a package installer in the future. - -<center>'''WARNING! You may need Administrator rights to install or use QB64!'''</center> +<center>'''You may need Administrator rights to install or use QB64.'''</center> ---- @@ -838,280 +806,15 @@ The ZIP file can be used to unzip the DLL libraries into any program's folder lo {{TextEnd}} <center>{{text|These files are no longer required and are no longer available except with older version downloads!|red}}</center> - -<center>'''This page and download will be updated when library additions or requirements change!'''</center> - <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> +==Q: Do you provide changelogs?== -==Q: What are the Specifications by SDL Version?== - -{{TextStart}} '''AUTOMATIC VERSION UPDATES''' - -IMPORTANT: QB64 V0.91 users onwards do not need to download ANY Updates! Simply click on -the QB64 FILE menu's [[IDE|UPDATE]] command (if QB64 hasn't already detected the new version) to -download newer versions. You can allow or block automatic updates in the Options Menu. - -Enjoy, -Galleon - - '''NOTE: Some auto-updates may take longer! Please allow them to finish completely.''' - The ''Help'' menu ''About'' will tell which version of QB64 is currently running. - The included ''Readme.txt'' file is also updated with the current version improvements. - '''All QB64 versions after Version .94 will contain the full MinGW C++ compiler.''' - - '''Note: QB64 is currently being converted to Open GL graphics. ''' - '''When fully implemented, DLL files will no longer be required.''' - - '''Latest Update April 20, 2012''' -V0.954 Specific =============== --Implements the '[[_MEM]]' memory variable interface for safe, fast, raw memory access [http://www.qb64.net/forum/index.php?topic=5967.msg61466#msg61466] --Patch applied for [[SHELL]] "consolecommand >somefile" in Win7 Professional (previously didn't work) -'''NOTE: This version is the last SDL version and will be updated as required until GL is fully incorporated.''' - -V0.953 Specific =============== March 10, 2012 --New commands added to allow the use of a console window and hide or display the main -program window: - [[$CONSOLE]] - [[_CONSOLE]] OFF/ON - [[_DEST]] [[_CONSOLE]] - [[$SCREENHIDE]] - [[$SCREENSHOW]] - [[_SCREENHIDE]] - [[_SCREENSHOW]] --Codes can now be sent by [[END]] or [[SYSTEM]] in a program. - END return_code - SYSTEM return_code --The [[SHELL (function)]] and [[_SHELLHIDE]] function can return the END or SYSTEM code sent. - return_code = SHELL("myprogram.exe") - return_code = _SHELLHIDE("myprogram.exe") --A couple of bugs addressed - -V0.952 Specific =============== February 26, 2012 --'''First automated symultaneous multiplatform release of QB64 across Windows, Linux & MacOSX''' --Some bugs addressed --Simple console usage added. '''A console window will now appear briefly when the IDE is run.''' - -V0.951 Specific =============== February 18, 2012 --Implements a range of important bug/incompatibility fixes but no new functionality - (see the bugs/incompatibilities forum for details) - - -V0.95 Specific === Primarily implements significant improvements to the IDE: 1/18/2012 --IDE is ~2x faster at checking programs --Recently opened files list --Bulk comment and uncomment --Saved code bookmarks for navigation --[[ASCII]] chart (and value of cursor's ASCII character shown) --Quick search field ═0 along with a ↨ list of things recently searched for --CONTROL+left/right arrow to move between words of text in code --Double click text in a single line text field to clear it --Copy (CTRL+C or CTRL+INS) and paste (CTRL+V or SHIFT+INS) into/from single line text fields --Mouse wheel scrolls lists (such as file lists in the open box) --Can press keyboard keys to jump through list items (before it just gave the first one - or in some cases didn't work at all) --View/open/edit/save files with any extension, not just .BAS --Backwards searching (SHIFT+F3) --When a code error is reported in the IDE you can click on the 'ON LINE 1022' part of the - message (which is now highlighted) to jump to that location in your code --HOME key now toggles between the absolute left hand side (like before) on the first press - and the first indented character of the line --Help system: - -Linked to WIKI - -Cached for speed but can be updated on request - -F1 for help about a keyword (or symbol) the cursor is currently on in your code - -Navigation ribbon for moving forward and backwards between recently viewed help pages - -Typing a word quickly finds links on help pages (useful on large index pages) - -Fully keyboard and/or mouse browsable - -F6 to transition between help window and code window - [[_SCREENIMAGE]] now supports four screen position parameters to get a portion of the desktop. - [[_CONTROLCHR]] OFF sets all ASCII control characters(0 to 31) as text characters. ON resets. - -V0.94 Specific === September 10, 2011 - '''Large Download will take about ONE HOUR through auto-update !''' - '''[http://www.qb64.net/forum/index.php?topic=4404.0 Download full MinGW C++ compiler V0.942 ZIP file update here for faster download!] - '''NOTE: After installing Version .94, Update to Version .942 from File menu!''' --[[DECLARE LIBRARY]] significantly improved: --[[_OFFSET]] integer variable type and [[_OFFSET (function)]] implemented for the storage of pointers -and offsets which varies across systems/implementations and will grow in the future. --[[DECLARE LIBRARY|DECLARE CUSTOMTYPE LIBRARY]], allows you to override the required types and use the variable - types you want, provided they are the same size - -[[DECLARE LIBRARY|DECLARE STATIC LIBRARY]], for specifying static linking over shared library linking - -Added DECLARE LIBRARY support to MacOSX & Linux including library versioning --SHELL [[SHELL|_DONTWAIT]] and [[_SCREENIMAGE]] implemented in MacOSX & Linux --[[_FILEEXISTS]] and [[_DIREXISTS]] functions added to check for file & path existance --''''Go to line', 'undo' & 'redo' added to [[IDE]]''' --Many bugs fixed, refer to bugs/incompatibilities forum --.'\internal\temp\recompile.bat/.sh/.command' batch/script file now autogenerated on run to - investigate C++ compilation issues when they arrise --'''Note: Windows version of QB64 now distributed with the full (not stripped down) version''' - '''of the MinGW C++ compiler. Update to v .942 after download and installation of v .94!''' - - -V0.936 Specific =============== June 26, 2011 --Implements the QB64 device interface which can handle joystick, keyboard and mouse - input in a common way by referring to buttons, axes & wheels: --New commands added: [[_DEVICES]], [[_DEVICEINPUT]] and [[_DEVICE$]] See: [http://www.qb64.net/forum/index.php?topic=3585.msg36876#msg36876 Example usage] - [[_AXIS]], [[_BUTTON]], [[_BUTTONCHANGE]], [[_WHEEL]], [[LASTAXIS]], [[_LASTBUTTON]], [[_LASTWHEEL]] --Implemented QBASIC's [[STICK]], [[STRIG]], [[STRIG(n)]] and [[ON STRIG(n)]] functionality: [http://www.qb64.net/forum/index.php?topic=3585.msg37802#msg37802 Example usage] --Fixed problem with [[_CONNECTIONADDRESS]] returning 'localhost' IP (external site this function - relied on changed their procedure). '''Will add optional $ suffix next release!''' - -V0.935 Specific =============== May 27, 2011 --Improvements to [[_MAPTRIANGLE]] - -Clipping bugs which caused program to crash fixed - -_MAPTRIANGLE _SEAMLESS ... option added so common edges aren't drawn twice, affecting alpha - dependent results - -Limits (-16383 to 16383) on coordinate positions imposed, as this is a software mapper for - speed reasons it has some limitations --[[_SETALPHA]] fixed (was broken by syntax checking upgrade) - -V0.934 Specific =============== --Fixed the critical problem which made the IDE freeze/crash after a period of usage - (Depending on the OS and RAM, the period could have been as short as a few minutes!) --Improved support MacOSX (Note: V0.933 was a Mac only version released via a link in the - bugs/incompatibilities forum) --New command added: [[_MAPTRIANGLE]] - Calling syntax: - _MAPTRIANGLE (10,10)-(10,20)-(20,20)[,sourceimage] TO (10,10)-(10,20)-(20,20)[,destimage] - What does it do? - It texture maps a triangular region from the source image onto the destination image. - What's supported: - -8bit, 32bit, [[_CLEARCOLOR]] and [[_ALPHA]] - Notes: - A software mapper, but an extrememly fast one. Could easily be used to make an image rotator - -V0.932 Specific =============== - '''This is an essential update which corrects problems added by V0.931 naming restrictions!''' - -Implements a totally revised set of rules governing name restrictions which offers far - greater QBASIC compatibility than V0.931 - -Reports as yet unimplemented QBASIC commands as 'not implemented' when you try to use them - -Bugs/Incompatibilities: - -Indwelling [[$INCLUDE]] problem fixed - -DELETE key after mouse click issue in IDE corrected - -Phantom errors' after correction of an invalid sub/function argument declaration in IDE fixed - '''Syntax for an off screen [[GET (graphics statement)|GET]] has changed to require a color parameter after the array name.''' - -V0.931 Specific ============ '''If you have this version PLEASE UPDATE to V0.932!''' --Implements robust syntax checking into all parts of the QB64 compiler: - -Naming restrictions - -Reserved name restrictions - -Duplicate name restrictions - -Checking for incorrect syntax - -Checking all types match correctly for SUB/FUNCTION calls - -and much more... --Minor bug-fixes/improvements - -[0.927] February 27, 2011 - [[_SNDRAW]] interface added along with [[_SNDRAWLEN]] and [[_SNDRATE]]. - (See http://www.qb64.net/forum/index.php?topic=2493.msg24885#msg24885) - Multiplatform improvements: - -Linux/MacOSX: Pop-up box on runtime errors - -Linux/MacOSX: _CLIPBOARD$ uses OS's clipboard, very useful in QB64 IDE for - cut/copy/paste operations - -Linux: DELETE key now works correctly - -MacOSX: Apple(Command)+X/C/V/A also supported in IDE - -MacOSX: CTRL+BREAK now works (CTRL+F15 on keyboards without a designated 'break' key) - -(Linux too?)/MacOSX: [[TIMER]] now begins on the correct value, before it always - started on the same value which also made RANDOMIZE TIMER do nothing! - Bugs/Incompatibilities: - -Severe memory leak related to GET/PUT fixed - -[0.926] January 30, 2011 - '''NOTE: This version reduces the size of QB64 compiled EXE files by as much as 44%!''' - The minimum compiled EXE size has been reduced from 875 KB to 495 KB. - - Newly implemented QBASIC commands: - [[KEY n|KEY ON]], [[KEY LIST]], [[ON KEY(n)]]..., [[KEY(n)]] ON/OFF/STOP, KEY index,string$, etc - [[PALETTE USING]] - New commands added to QB64: - [[_SCREENMOVE]] newwindowxposition,newwindowyposition - _SCREENMOVE _MIDDLE 'center window on desktop - mywindowxposition = [[_SCREENX]] 'set window's desktop position - mywindowyposition = [[_SCREENY]] - [[_MOUSEMOVE]] xoffset,yoffset 'moves the mouse cursor - myosinfo$ = {{Cb|_OS$}} (See http://www.qb64.net/forum/index.php?topic=2495.0) - Critical bugs fixed in: - PRINT USING - EOF - handling of NOT operator - passing multiple arrays to functions - KILL - READ - Other minor problems addressed - -There is a new menu item in the 'Options' menu called 'About' which will tell you which -version of QB64 you have. After this update it will say 0.926 - - '''V0.92 Updates October 17, 2010''' -[0.923] {{Cb|DECLARE LIBRARY}} command added to allow for calling functions in external libraries - (http://www.qb64.net/forum/index.php?topic=1712.0) -[0.923] Various minor bugs/incompatibilities fixed - -[0.922] QB64 IDE can now use codepages, select them in the options->language... section. - Note: A .TTF font MUST be in use to see the results. -[0.922] New command: [[_MAPUNICODE]] unicodevalue TO asciivalue 'Maps UNICODE codes to ASCII - values for purposes such as simulating codepages -[0.922] New command: unicodevalue=_MAPUNICODE(asciivalue) 'Returns the UNICODE code that the - ascii value is currently mapped to -[0.922] Linux version updated -[0.922] Significant bugs/incompatibilities corrected, including: - -corrections to the passing of UDT members by reference - -fixed memory leak in [[_FREEIMAGE]] (as _FREEIMAGE is called internally by QB64 for - SCREEN management, it also affected some programs not calling _FREEIMAGE) - -corrected mismatch in dimension count of multidimensional arrays passed to functions - -corrections to the implementation of the FIELD statement - (for other bugs/incompatibilities addressed, refer to the forum) -[0.921] Various bug fixes and patches applied to V0.92 - - '''V0.92 Specific October 4, 2010''' - --Significant improvements to the QB64 input system have occurred primarily for multilingual - and multiplatform reasons: - i) The new [[_KEYHIT]] and [[_KEYDOWN]] functions can be used to monitor key press/release -events/states. - These also return UNICODE (UTF32) codes when UNICODE characters are entered. - http://www.qb64.net/forum/index.php?topic=1368.msg12703#msg12703 - ii) IME support added to facilitate entering Japanese, Chinese and Korean characters. - Note: The font CYBERBIT.TTF is free for non-commercial use and is now included in QB64. - It is only required to facilitate input via IME and not loaded unless the user - switches to an IME input system mode. - QB64 also locates several fall-back fonts under circumstances when 'cyberbit' - is not present, therefore it is unnecessary to distribute this font with your programs. - iii) QB64 now maps the UNICODE input of characters which appear in the CP437 extended - range(128-255) to their correct character. This means characters with umlauts and - other international characters now appear correctly when using INKEY$ - iv) QB64 emulates scancodes based on what a stock-standard 101-key keyboard might - return. Scancodes are language/platform specific, so this change means programs - which do use INP will work as expected on all platforms. --Support for the FIELD statement added. --Some bugs/incompatibilities addressed but others will be corrected over coming weeks - via automatic updates. - (See the bugs/incompatibilities forum for further information) - - '''V0.91 Updates August 22, 2010''' - - -The DATA folder (and its contents) are no longer required. You may delete them - when/if you wish. - -Various bugs & incompatibilites addressed http://www.qb64.net/forum/index.php?board=3.0 - (of note: FREEFILE, FIX, INT, INPUT, INCLUDE) - -Improved syntax checking - -Removed blank pixel lines occurring between box drawing characters when using .TTF fonts - 7/8/2010: - -FILES command implemented - - '''V0.91 Specific''' - - -Primarily implements the QB64 auto-updater. - http://www.qb64.net/forum/index.php?topic=1110.msg8195#msg8195 - QB64 now checks for and applies updates to QB64 automatically or according to the update - options you specify in the IDE. - - '''V0.9 Specific July 11, 2010''' - -(Linux users must now run the batch/script file 'setup.sh' to build/setup/install QB64) --Primarily updates Linux pure 64-bit support --C++ components have been overhauled to be 64-bit compatible (affects all versions of QB64) --Further bugs/incompatibilities fixed (see forum for details) --Samples have been checked for Linux compatibility (eg. case sensitive filenames) - -{{TextEnd}} +We do. Check below: +* [[Version .9 changelog]] +* [[Version 1.000 changelog]] +* [[Version 1.1 changelog]] <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> @@ -1119,7 +822,7 @@ events/states. A: Yes, as of version 0.85 a licence comes with QB64 released as freeware. Read the licence.txt that comes with the download package for more information. QB64 will always be free to use with the current library files and the licenses DO NOT LIMIT the use of those libraries! You are also allowed to sell software that you create with the following stipulations: -{{TextStart}} '''QB64 SOFTWARE LICENSE''' +{{TextStart}} '''QB64 SDL SOFTWARE LICENSE''' QB64 is currently released as freeware meaning that this download may be copied/distributed free of charge. All rights to the programs you create using QB64 (in both their executable @@ -1152,9 +855,136 @@ The official version of MINGW GCC compiler can be found at the following URL: http://www.mingw.org/ '' '' {{TextEnd}} + :The choice of license makes a big difference: using the '''Lesser GPL''' permits use of the library in proprietary programs; using the ordinary GPL for a library makes it available only for free programs. +<Center>'''QB64 GL License found in the License folder with other licenses:'''</center> +{{TextStart}} + '''IMPORTANT LICENSING NOTE FOR QB64 GL PROGRAMMERS''' +All executables which perform any kind of sound operation are subject to the LGPL license +(due to incorporation of mpglibdll and OpenAL). +Other components are licensed under various permissive licences. +When sound components are included (thus the LGPL is in effect), the easiest way to meet +terms of the LGPL is to make your program's source code (.BAS) available. +'''If you are not using sound components, you do not need to release the program's source.''' +'''If you are using fonts, you are bound by the terms of FreeType's license.''' Somewhere +in your software package should include a notice that your program includes the FreeType +library (see licence_freetype_ftl.txt for details) +'''In all cases, you should distribute the LICENSE folder with your program.''' + +It should be noted that providing source code is not the only way to meet the conditions of +the LGPL (eg dynamic linking) but it is by far the easiest from a technical point of view at +this current time. + + +The license requirements for components of QB64 are as follows: + +Software/Library Name: QB64 (inclusive of all parts of this distribution not covered by +separate licence below) +Website(s): http://www.qb64.net, http://code.google.com/p/qb64/ +License: LGPL with static linking of code required for generated programs to run permitted +License Website: http://www.gnu.org/licenses/licenses.html#LGPL +License File: license/lgpl_2_1.txt + +Software/Library Name: MinGW 64 +Website: http://mingw-w64.sourceforge.net/ +License: (see below) +Each of the various packages, which is distributed by MinGW.org, is governed by its own +individual copyright and licensing terms. In summary, for the most commonly deployed +packages: +MinGW runtime: The MinGW base runtime package has been placed in the public domain, and +is not governed by copyright. This basically means that you can do what you like with the +code.w32api: You are free to use, modify and copy this package. No restrictions are imposed +on programs or object files linked with this library. You may not restrict the the usage of +this library. You may distribute this library as part of another package or as a modified +package if, and only if, you do not restrict the usage of the portions consisting of this +(optionally modified) library. If distributed as a modified package, then a copy of this +notice must be included. +This library is distributed in the hope that it will be useful, but WITHOUT WARRANTY OF +ANY KIND; without even the implied warranties of MERCHANTABILITY or of FITNESS FOR A +PARTICULAR PURPOSE. +MinGW profiling code: MinGW profiling code is distributed under the terms of the GNU General +Public License. +Binutils, GCC, GDB, GNU Make: All of the GNU development tools, such as GNU binutils, GCC, +GDB and GNU Make, are governed by the terms of the GNU General Public License. +License Website: http://www.gnu.org/licenses/licenses.html#GPL +License File: license_gnu_gpl_3.txt +Location in QB64 distribution: internal/c/c_compiler/ + +Software/Library Name: Opus Tools +Website: http://www.opus-codec.org/ +License: BSD 2-clause license +License Website: http://opensource.org/licenses/BSD-2-Clause +License File: license_opus.txt +Location in QB64 distribution: internal/c/parts/audio/conversion/ +OpusInfo, which is under a GPL licence, was included in Opus Tools but has been removed +from the QB64 distribution. + +Software/Library Name: mpglibdll +Website(s): +http://www.rz.uni-frankfurt.de/~pesch +http://www.mpg123.de +http://www.sulaco.org/mp3 +License: LGPL 2.1 +License Website: http://www.gnu.org/licenses/licenses.html#LGPL +License File: license_gnu_lgpl_2_1.txt +Location in QB64 distribution: internal/c/parts/audio/decode/mp3/ + +Software/Library Name: Ogg Vorbis I audio decoder version 1.05 +Website:http://nothings.org/stb_vorbis/ +Date:Written in April 2007 +Author:Sean Barrett, sponsored by RAD Game Tools +License: Placed in the public domain April 2007 by the author: no copyright is claimed, and +you may use it for any purpose you like. +License Website: N/A - public domain +License File: license_stbvorbis.txt +Location in QB64 distribution: internal/c/parts/audio/decode/ogg/ + +Software/Library Name: OpenAL-soft +Website:http://kcat.strangesoft.net/openal.html +License: LGPL 2 +License Website: http://www.gnu.org/licenses/licenses.html#LGPL +License File: license_gnu_lgpl_2.txt +Location in QB64 distribution: internal/c/parts/audio/out/ + +Software/Library Name: FreeGLUT +Website: http://freeglut.sourceforge.net/ +License: LGPL (note: website states LGPL, license file is not a copy of GNU LGPL) +License Website: http://www.gnu.org/licenses/licenses.html#LGPL +License File: license_freeglut.txt +Location in QB64 distribution: internal/c/parts/core/ + +Software/Library Name: FreeTYPE +Website: http://www.freetype.org/ +License: GPL or FreeTYPE's FTL (programs must abide by one of these licenses) +License Website(s): (see below) +http://www.freetype.org/license.html +http://www.gnu.org/licenses/licenses.html#GPL +License File(s): (see below) +license_freetype_ftl.txt +license_gnu_gpl_2.txt +Location in QB64 distribution: internal/c/parts/video/font/ttf/ + +Software/Library Name: NanoJPEG - KeyJ's Tiny Baseline JPEG Decoder +Author: Martin J. Fiedler <martin.fiedler@gmx.net> +License: (refer to license file) +License File: nanojpeg_license.txt +Location in QB64 distribution: internal/c/parts/video/image/decode/jpg + +Software/Library Name: NanoJPEG - KeyJ's Tiny Baseline JPEG Decoder +Author: Martin J. Fiedler <martin.fiedler@gmx.net> +License: (refer to license file) +License File: license_nanojpeg.txt +Location in QB64 distribution: internal/c/parts/video/image/decode/jpg + +Software/Library Name: LodePNG +License: (refer to license file) +License File: license_lodepng.txt +Location in QB64 distribution: internal/c/parts/video/image/decode/png +{{TextEnd}} + + <center> '''The creator of QB64 is NOT responsible for any damages or the intended use of the software it creates!'''</center> <center>'''The user assumes all risk when they download or use the QB64 compiler!'''</center> @@ -1164,7 +994,16 @@ The official version of MINGW GCC compiler can be found at the following URL: ==Q: How can I find what caused a Compiler error?== -A: Compiler errors are often actually coding errors that both you and the IDE don't notice! Often it is a syntax error such as forgetting a quotation mark in a PRINT. Look for syntax errors too as the IDE still needs some improvements. The best way to get a clue to the problem is to run the following batch file IMMEDIATELY AFTER a compilation failure: '''CODE UPDATED 1/4/2011''' +A: Compiler errors are often actually coding errors that both you and the IDE don't notice! Often it is a syntax error such as forgetting a quotation mark in a PRINT. Look for syntax errors too. + +* You will find a script/batch file called '''recompile_win.bat''' (also '''recompile_osx.command''' or '''recompile_lnx.sh''', according to your operating system) inside the folder '''internal\temp''' (if you have more than one instance of the IDE open, look inside temp2, temp3, etc). +* Immediately after encountering a "C++ compilation failed" message, run this script to have a look at the error message returned by the gcc compiler. That usually helps track the issue. + + +---- + + +''For versions of QB64 below .954, the best way to get a clue to the problem is to run the following batch file IMMEDIATELY AFTER a compilation failure: '''CODE UPDATED 1/4/2011''''' <center>'''{{text|It's a good idea to exclude "QB64.exe" from any real-time anti-virus scanning to prevent IDE Module Errors!|red}}'''</center> @@ -1211,9 +1050,6 @@ PAUSE '' '' <center>'''To create the Batch file, copy code above to Notepad and save it as ''QB64ERR.BAT''. Save as type: ''All Files''.'''</center> -<center>[http://bit.ly/Oa6Ha0 Download the QB64 Editor and Compiler Shortcuts and Compile Error Batch Files]</center> - - Look for the word '''error''' in the resulting information. The errors often have to do with syntax or code errors not found by the [[IDE]]. <center>'''Place the batch files into the QB64 folder to use.'''</center> @@ -1223,7 +1059,9 @@ Look for the word '''error''' in the resulting information. The errors often hav ==Q: How do I use the QB64 code Repository?== -A: You can find a video tutorial here: [http://www.qb64.net/qb64_repository_tutorial.mp4 Repository Video Tutorial] +A: QB64 is open source freeware and all the codebase is freely available on GitHub at [https://github.com/Galleondragon/qb64 this link]. You can fork it, develop your own modified version of it and '''most importantly: help improve the official version by making pull requests.''' If you are already familiar with code collaboration, versioning control using git and would like to help, become involved! Your contributions could end up becoming part of the QB64 project. + +<!-- You can find a video tutorial here: [http://www.qb64.net/qb64_repository_tutorial.mp4 Repository Video Tutorial] --> :: '''I cannot stress enough that the QB64 repository is not an official QB64 release! Even though our contributors are individually appointed, I'm not responsible for the contributions of these other authors which could potentially be malicious. ''' @@ -1233,9 +1071,8 @@ A: You can find a video tutorial here: [http://www.qb64.net/qb64_repository_tuto <p style="text-align: center">([[#toc|Return to FAQ topics]])</p> -==Q: where I can view the C++ code before it gets compiled== -Look in the QB64 '''internal\temp''' folder for '''Main.txt''' to get the C code used to compile the latest program. - +==Q: Where I can view the C++ code before it gets compiled== +Look in the QB64 '''internal\temp''' folder for '''main.txt''' to get the C code used to compile the latest program. ==Q: Where can I find information about a QB64 statement or function?== @@ -1260,9 +1097,4 @@ Look in the QB64 '''internal\temp''' folder for '''Main.txt''' to get the C code <center>[[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keywords Not Supported in Linux or MAC OSX versions]]</center> -<center>''Offline WIKI Download provided by OlDosLover:''</center> - -<p style="text-align: center"> [https://dl.dropbox.com/u/10291175/QB64OfflineWiki.7z Download the QB64 WIKI for Offline Reference (7 Zip 5MB)].</p> - - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/READ.txt b/internal/help/READ.txt index 084d87d92..7371f6823 100644 --- a/internal/help/READ.txt +++ b/internal/help/READ.txt @@ -1,19 +1,20 @@ -The '''READ''' statement reads values from a DATA field and assigns them to variables. +The '''READ''' statement reads values from a [[DATA]] field and assigns them to one or a comma separated list of variables. {{PageSyntax}} -::: READ value1$[, value2!, value3%, ...] +::: [[READ]] value1$[, value2!, value3%, ...] -* READ statements assign variables to DATA statement values on a one-to-one basis. -* READ statement variables may be numeric or string, and the values read must agree with the variable types specified. If they do not agree, a "Syntax error" results. -* A single READ statement may access one or more DATA values. They are accessed in order. -* Several READ statements may access the same DATA statement at different positions. -* [[STRING]] READ variables can read unquoted numerical DATA values also so beware! -* Quoted DATA can only be READ using a [[STRING]] variable or an [[ERROR Codes|error]] will occur! -* If the number of variables specified is fewer than the number of elements in the DATA statement(s), subsequent READ statements begin reading data at the first unread element. If there are no subsequent READ statements, the extra data is ignored. -* To reread DATA statements from the start, use the [[RESTORE]] statement with or without a line label as required. -* If the number of variables in list of variables exceeds the number of elements in the DATA field(s), an [[ERROR Codes|"Out of data" error]] will occur! +* READ statements assign variables to [[DATA]] statement values on a one-to-one basis sequentially. +* A single READ statement may access one or more [[DATA]] values. They are accessed in the order set. +* Several READ statements may access the same [[DATA]] statement block at the following sequential position. +* [[DATA]] can be READ using [[STRING]] or numerical [[TYPE]] variables singularly or in a comma separated list: +:: [[STRING]] READ variables can read quoted or unquoted text or numerical DATA values! +:: Numerical type READ variables can only read '''unquoted''' numerical DATA values! +::'''If they do not agree, a [[ERROR Codes|"Syntax error"]] may result when run reading string data as numerical values!''' +* If the number of variables specified is fewer than the number of elements in the DATA statement(s), subsequent READ statements begin reading data at the next unread element. If there are no subsequent READ statements, the extra data is ignored. +* If variable reads exceed the number of elements in the DATA field(s), an [[ERROR Codes|"Out of data" error]] will occur! +* Use the [[RESTORE]] statement to reread DATA statements from the start, with or without a line label as required. * [[ACCESS]] READ can be used in an [[OPEN]] statement to limit file access to read only, preserving file data. * '''WARNING! Do not place DATA fields after [[SUB]] or [[FUNCTION]] procedures! QB64 will FAIL to compile properly!''' : Qbasic allowed programmers to add DATA fields anywhere because the [[IDE]] separated the main code from other procedures. @@ -59,6 +60,8 @@ The '''READ''' statement reads values from a DATA field and assigns them to vari ''See also:'' * [[DATA]], [[RESTORE]] +* [[PRINT USING]] +* [[OPEN]] FOR [[INPUT (file mode)|INPUT]] {{text|(file statement)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/RESUME.txt b/internal/help/RESUME.txt index 9bb895d21..59e015dd8 100644 --- a/internal/help/RESUME.txt +++ b/internal/help/RESUME.txt @@ -1,18 +1,18 @@ -The '''RESUME''' statement is used with [[NEXT]] or a linenumber or label in an Error handling routine ONLY. - +The '''RESUME''' statement is used with '''NEXT''' or a line number or label in an error handling routine. {{PageSyntax}} -:: '''RESUME''' {[[NEXT]]|''linelabel''|''linenumber''} +: [[RESUME]] {'''NEXT'''|{{Parameter|lineLabel}}|{{Parameter|lineNumber}}} -* [[NEXT]] returns execution to the code immediately following the error. -* A ''[[line number]]'' or ''line label'' is the code line to return to after an error. +{{PageDescription}} +* '''NEXT''' returns execution to the code immediately following the error. +* A {{Parameter|lineLabel}} or {{Parameter|lineNumber}} is the code line to return to after an error. * If the line label or number is omitted or the line number = 0, the code execution resumes at the code that created the original error. -* RESUME can only be used in ERROR handling routines! Use [[RETURN]] in normal [[GOSUB]] procedures. +* [[RESUME]]can only be used in ERROR handling routines. Use [[RETURN]] in normal [[GOSUB]] procedures. -''See also:'' +{{PageSeeAlso}} * [[ON ERROR]], [[ERROR]] * [[RETURN]], [[ERROR Codes]] * [[FOR...NEXT]] (counter loop) diff --git a/internal/help/RUN.txt b/internal/help/RUN.txt index 7149f18d1..90813473f 100644 --- a/internal/help/RUN.txt +++ b/internal/help/RUN.txt @@ -1,5 +1,7 @@ '''RUN''' is a control flow statement that clears and restarts the program currently in memory or executes another specified program. +The multi-modular technique goes back to when QBasic and QuickBASIC had module size constraints. In QB64 it has been implemented so that that older code can still be compiled, though '''it is advisable to use single modules for a single project (not counting [[$INCLUDE]] libraries), for ease of sharing and also because the module size constraints no longer exist.''' + {{PageSyntax}} @@ -21,11 +23,14 @@ * RUN does not return to the calling procedure if the program called is not a Qbasic procedure! * RUN closes all open files and closes the invoking program module before the called program starts. (Cannot use Basica's R) * If you do NOT want opened files to be closed use [[CHAIN]] instead. -* In Qbasic '''/RUN''' can also be used to run a program module in a command line. Example: QB.EXE /L /RUN Module1.BAS -* RUN should reset the [[RANDOMIZE]] sequence to the starting [[RND]] function value.(Not yet in QB64) +* RUN should reset the [[RANDOMIZE]] sequence to the starting [[RND]] function value.(Not in QB64) * Note: Qbasic also allowed /RUN in a command line call to run a BAS file with the interpreter. QB64 cannot run BAS files! * '''Note: RUN causes a stack leak in QB64 if it is called from within a [[SUB]] or [[FUNCTION]]. Avoid when possible!''' -* '''NOTE: [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions |Not currently available in Linux or Mac operating systems!]]''' +* '''NOTE: [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions |Not available in Linux or Mac operating systems.]]''' + + +''QBasic/QuickBASIC:'' +* In Qbasic '''/RUN''' can also be used to run a program module in a command line. Example: QB.EXE /L /RUN Module1.BAS ''Example 1:'' Shows how RUN can reference multiple line numbers in the main module code. No line number executes first code line. diff --git a/internal/help/SCREEN.txt b/internal/help/SCREEN.txt index 25ad56669..a55ff4e28 100644 --- a/internal/help/SCREEN.txt +++ b/internal/help/SCREEN.txt @@ -190,7 +190,7 @@ col% = ({{Cl|POS}}(0) - 1) * {{Cl|_PRINTWIDTH}}("W") 'finds current pa {{small|Code by Ted Weissgerber}} : ''Explanation:'' The procedure above creates a larger version of a SCREEN 13 window by stretching it with [[_PUTIMAGE]]. It cannot stretch PRINTed text so [[_PRINTSTRING]] must be used instead. [[LOCATE]] sets the PRINT cursor position for [[CSRLIN]] and [[POS]](0) to read. The SUB then converts the coordinates to graphical ones. Then '''change''' [[PRINT]] to PRINTS using the '''Search Menu'''. -<center>[http://dl.dropbox.com/u/8440706/HOWIE.zip Download of Example 2 Bitmap images]</center> +<center>[https://www.dropbox.com/s/tcdik1ajegbeiz4/HOWIE.zip?dl=0 Download of Example 2 Bitmap images]</center> <center>You can easily change PRINT to the PRINTS sub-procedure name in your code using the [[IDE]] ''Search'' Menu ''Change'' option.</center> diff --git a/internal/help/SELECT_CASE.txt b/internal/help/SELECT_CASE.txt index 0455690a8..bf7d21fd0 100644 --- a/internal/help/SELECT_CASE.txt +++ b/internal/help/SELECT_CASE.txt @@ -1,36 +1,40 @@ -'''SELECT CASE''' is used to determine the program flow by comparing the value of a variable to specific CASE values. +[[SELECT CASE]] is used to determine the program flow by comparing the value of a variable to specific CASE values. {{PageSyntax}} -:::'''SELECT''' [EVERY]'''CASE''' ''checkvalue'' -::::[[CASE]] -::::[[CASE IS]] -::::[[CASE ELSE]] -:::'''[[END SELECT]]''' +:'''SELECT''' [EVERY]'''CASE''' {{Parameter|testExpression}} +::'''CASE''' {{Parameter|expressionList1}} +:::[statement-block1] +::['''CASE''' {{Parameter|expressionList2}} +:::[statement-block2]]... +::['''CASE ELSE''' +:::[statementblock-n]] +:'''END SELECT''' -* '''SELECT CASE''' evaluates a comparison ''checkvalue'' and executes the first matching [[CASE]] or [[CASE ELSE]] and exits. -* '''SELECT EVERYCASE''' allows the execution of all matching [[CASE]] statements from top to bottom or [[CASE ELSE]]. -* The literal or variable or expression ''checkvalue'' comparison can result in any string or numerical type. -* '''Note:''' A ''checkvalue'' variable value can be changed inside of true CASE evaluations in SELECT EVERYCASE. -* A ''checkvalue'' derived from an expression or [[FUNCTION]] will only be determined once at the start of the block execution. -* Supports individual CASE values and ranges or lists of literal values as below: -:* [[CASE]] casevalue: code {{text|''''case compares one numerical or text value'''}} -:* [[CASE]] casevalue1 [[TO]] casevalue2: code {{text|''''case compares a range of values '''}} -:* [[CASE]] casevalue1, casevalue2, casevalue3: code {{text|''''case compares a list of values separated by commas'''}} -:* [[CASE IS]] > casevalue: code {{text|''''case compares a value as <nowiki> =, <>, < or > </nowiki>'''}} -:* [[CASE ELSE]]: code {{text|''''bottom case statement executes only when no other CASE is executed.}}''' -* The CASE values should cover the normal ranges of the comparison ''variable'' values. -* Use [[CASE ELSE]] before [[END SELECT]] if an alternative is necessary when no other case matches. +* '''SELECT CASE''' evaluates {{Parameter|testExpression}} and executes the first matching [[CASE]] or [[CASE ELSE]] block and exits. +* '''SELECT EVERYCASE''' allows the execution of all matching [[CASE]] blocks from top to bottom or the [[CASE ELSE]] block. +* The literal, variable or expression {{Parameter|testExpression}} comparison can result in any string or numerical type. +* '''Note:''' A {{Parameter|testExpression}} variable value can be changed inside of true CASE evaluations in SELECT EVERYCASE. +* A {{Parameter|testExpression}} derived from an expression or [[FUNCTION]] will only be determined once at the start of the block execution. +* <span id="allCASES">Supports individual CASE values and ranges or lists of literal values as below:</span> +** '''CASE''' casevalue: code {{text|''''case compares one numerical or text value'''}} +** '''CASE''' casevalue1 [[TO]] casevalue2: code {{text|''''case compares a range of values '''}} +** '''CASE''' casevalue1, casevalue2, casevalue3: code {{text|''''case compares a list of values separated by commas'''}} +** '''CASE IS''' > casevalue: code {{text|''''case compares a value as <nowiki> =, <>, < or > </nowiki>'''}} +** '''CASE ELSE''': code {{text|''''bottom case statement executes only when no other CASE is executed.}}''' +* The CASE values should cover the normal ranges of the comparison {{Parameter|testExpression}} values. +* Use '''CASE ELSE''' before '''END SELECT''' if an alternative is necessary when no other case matches. * CASEs should be listed in an ascending or descending values for best and fastest results. * [[STRING]] comparisons will be based on their respective [[ASCII]] code values where capital letters are valued less than lower case. -* Use SELECT CASE when [[IF...THEN]] statements get too long or complicated. -* SELECT CASE and EVERYCASE statement blocks must '''always''' be ended with [[END SELECT]]! -* Use '''[[colon]]s''' to execute multiple statements in a one line statement. You cannot use [[AND]] for multiple statements! -* An '''[[underscore]]''' can be used anywhere after the code on one line to continue it to the next line in '''QB64 ONLY'''. +* Use '''SELECT CASE''' when [[IF...THEN]] statements get too long or complicated. +* '''SELECT CASE''' and '''EVERYCASE''' statement blocks must '''always''' be ended with [[END SELECT]]. +* Use '''[[colon]]s''' to execute multiple statements in one line. +* An '''[[underscore]]''' can be used anywhere after the code on one line to continue it to the next line in '''QB64'''. +{{PageExamples}} ''Example 1:'' SELECT CASE can use literal or variable [[STRING]] or numerical values in CASE comparisons: {{CodeStart}} '' '' {{Cl|INPUT}} "Enter a whole number value from 1 to 40: ", value @@ -126,10 +130,10 @@ value3$ = "z" {{Cl|CASE ELSE}}: {{Cl|PRINT}} "other value" 'key entry below A including all numbers {{Cl|END SELECT}} '' '' {{CodeEnd}} -: ''Notes:'' [[STRING]] values using multiple characters will be compared by the [[ASCII]] code values sequentially from left to right. Once the equivalent code value of one string is larger than the other the evaluation stops. This allows string values to be compared and sorted alphabetically using [[Greater Than|>]] or [[Less Than|<]] and to [[SWAP]] values in [[arrays]] irregardless of the string lengths. +: ''Notes:'' [[STRING]] values using multiple characters will be compared by the [[ASCII]] code values sequentially from left to right. Once the equivalent code value of one string is larger than the other the evaluation stops. This allows string values to be compared and sorted alphabetically using [[Greater Than|>]] or [[Less Than|<]] and to [[SWAP]] values in [[arrays]] regardless of the string lengths. -''Example 5:'' EVERYCASE allows sections of digital numbers to be drawn in a simulated LED readout using numbers from 0 to 9: +''Example 5:'' EVERYCASE is used to draw sections of digital numbers in a simulated LED readout using numbers from 0 to 9: {{CodeStart}} {{Cl|SCREEN}} 12 DO @@ -155,12 +159,10 @@ DO {{Cl|END SELECT}} {{Cl|LOOP}} {{Cl|UNTIL}} num > 9 {{CodeEnd}} -: '''Note:''' [[CASE ELSE]] will only execute if no other CASE is true! Changing the comparison value in a CASE may affect later CASE evaluations! '''Beware of duplicate variables inside of cases affecting the comparison values and remaining cases!''' +: '''Note:''' [[CASE ELSE]] will only execute if no other CASE is true! Changing the comparison value in a CASE may affect later CASE evaluations. '''Beware of duplicate variables inside of cases affecting the comparison values and remaining cases.''' -''See also:'' -* [[CASE]], [[CASE IS]] -* [[CASE ELSE]] +{{PageSeeAlso}} * [[IF...THEN]], [[Boolean]] diff --git a/internal/help/SETMEM.txt b/internal/help/SETMEM.txt index 710057a0a..59a9e00e8 100644 --- a/internal/help/SETMEM.txt +++ b/internal/help/SETMEM.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The '''SETMEM''' function is used to increase, decrease or return the current "far heap" byte size. @@ -8,7 +14,7 @@ The '''SETMEM''' function is used to increase, decrease or return the current &q ''Description:'' -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * SETMEM(0) returns the total number of bytes currently in the far heap memory area. * The byte size indicates the number of bytes to increase or decrease the far heap. :* If the byte size is negative, SETMEM decreases the far heap by the indicated number of bytes. diff --git a/internal/help/SHELL.txt b/internal/help/SHELL.txt index a2328a04b..0d96f03ea 100644 --- a/internal/help/SHELL.txt +++ b/internal/help/SHELL.txt @@ -7,14 +7,14 @@ The '''SHELL''' statement allows a program to use [[STRING]] OS command lines in -* If the ''[[DOS]]Command$'' {{KW|STRING}} parameter isn't used the "console" is opened. -* If {{KW|_DONTWAIT}} is used the '''QB64''' program doesn't wait for the SHELLed program/command to end. -* When the {{KW|_HIDE}} action is used, the [[CONSOLE|console]] window is hidden and screen info can be "redirected"(>) to a file (recommended). -* Commands are external [[DOS]] commands as {{KW|STRING|strings}} enclosed in quotes or string variables. -* Commands can be a mixture of {{KW|STRING|strings}} and string variables added together using the + [[concatenation]] operator. +* If the ''[[DOS]]Command$'' [[STRING]] parameter isn't used the "command console" is opened. +* If [[_DONTWAIT]] is used the '''QB64''' program doesn't wait for the SHELLed program/command to end. +* When the [[_HIDE]] action is used, the [[CONSOLE|console]] window is hidden and screen info can be "redirected"(>) to a file (recommended). +* Commands are external [[DOS]] commands as [[STRING|strings]] enclosed in quotes or string variables. +* Commands can be a mixture of [[STRING|strings]] and string variables added together using the + [[concatenation]] operator. * Command text can be in upper or lower case. Use single spacing between items and options. -* '''QB64''' automatically uses CMD /C when using [[SHELL]], but is allowed in old code. {{text|Note: CMD alone may lock up program!|red}} -* '''Note:''' Some commands may not work without adding CMD /C to the start of the command line. +* '''QB64''' automatically uses CMD /C when using [[SHELL]], but is allowed in command. {{text|Note: CMD alone may lock up program!|red}} +:: '''Note: Some commands may not work without adding CMD /C to the start of the command line.''' * '''QB64''' program screens will not get distorted, minimized or freeze the program like Qbasic fullscreen modes will. * '''QB64''' can use long path folder names and file names and [[SHELL]] command lines can be longer than 124 characters! * In Windows use additional [[CHR$]](34) quotation marks around folder or file names that contain spaces. @@ -96,11 +96,29 @@ PathExist% = 0 :''Explanation: IF Exist'' checks for the drive path. ''\Nul'' allows an emply folder at end of path. ''Echo'' prints '''yes''' in the file if it exists. +''Snippet 1:'' When looking for '''printers''' this command gives you a file list with the default printer '''True''': +{{TextStart}}{{Cb|SHELL}} {{Cb|_HIDE}} "CMD /C" + "wmic printer get name,default > default.txt" +{{TextEnd}} +'''Created file's text:''' +{{TextStart}}Default Name + FALSE Microsoft XPS Document Writer + TRUE HP Photosmart C7200 series + FALSE HP Officejet Pro 8600 + FALSE Fax +{{TextEnd}} +: ''Explanation:'' [[LINE INPUT]] could be used to find the printer names as [[STRING]] variables. -''See example:'' [[FILELIST$ (function)]] (member file search routine) - -''See Library:'' File Exist C++ Function that does not create a temp file. [[Windows_Libraries#File_Exist|FileExist Library Function]] +''Snippet 2:'' Here is the code to set the default printer to the "HP Officejet Pro 8600": +{{TextStart}}SHELL _HIDE "CMD /C" + "wmic printer where name='HP Officejet Pro 8600' call setdefaultprinter" +{{TextEnd}} +: After executing this program, and then running the first snippet again, we see the following '''contents of the text file:''' +{{TextStart}}Default Name + FALSE Microsoft XPS Document Writer + FALSE HP Photosmart C7200 series + TRUE HP Officejet Pro 8600 + FALSE Fax +{{TextEnd}} ''See also:'' @@ -116,6 +134,11 @@ PathExist% = 0 * [[FILELIST$]], [[DIR$]] {{text|(member file list array functions)}} +''See example:'' [[FILELIST$ (function)]] (member file search routine) + +''See Library:'' File Exist C++ Function that does not create a temp file. [[Windows_Libraries#File_Exist|FileExist Library Function]] + + ---- ''References:'' * [[DOS]], [[Batch Files]], [[VB Script]] diff --git a/internal/help/SIGNAL.txt b/internal/help/SIGNAL.txt index 85ba1ab85..6a5a11bba 100644 --- a/internal/help/SIGNAL.txt +++ b/internal/help/SIGNAL.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The SIGNAL keyword was reserved for OS/2 systems (protected mode). See the example for more information about how and why it is used. @@ -7,7 +13,7 @@ The SIGNAL keyword was reserved for OS/2 systems (protected mode). See the examp :: SIGNAL(number) [[ON]] -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * It will only work with compiler 6.00 and 6.00b and Basic PDS 7.00 when compiling in protected mode under OS/2. In all other situations, a SIGNAL statement results in an "Advanced feature unavailable" error message. diff --git a/internal/help/SIN.txt b/internal/help/SIN.txt index 5056dd20f..35092a001 100644 --- a/internal/help/SIN.txt +++ b/internal/help/SIN.txt @@ -6,7 +6,7 @@ The {{KW|SIN}} function returns the vertical component or sine of an angle measu {{Parameters}} -* The ''radian_angle'' must be measured in radians. +* The ''radian_angle'' must be measured in radians from 0 to 2 * Pi. {{PageDescription}} @@ -91,6 +91,7 @@ m = Teeth * G {{CodeStart}} '' '' {{Cl|SCREEN}} 12 Pi2! = 8 * {{Cl|ATN}}(1): sec! = Pi2! / 60 ' (2 * pi) / 60 movements per rotation +{{Cl|CIRCLE}} (320, 240), 80, 1 {{Cl|DO}} {{Cl|LOCATE}} 1, 1: {{Cl|PRINT}} {{Cl|TIME$}} Seconds% = {{Cl|VAL}}({{Cl|RIGHT$}}({{Cl|TIME$}}, 2)) - 15 ' update seconds diff --git a/internal/help/SYSTEM.txt b/internal/help/SYSTEM.txt index 55fba8f62..87615a480 100644 --- a/internal/help/SYSTEM.txt +++ b/internal/help/SYSTEM.txt @@ -1,4 +1,4 @@ -The {{KW|SYSTEM}} statement immediately closes a program and in DOS and can avoid returning to the QBasic [[IDE]]. +The {{KW|SYSTEM}} statement immediately closes a program and returns control to the operating system. {{PageSyntax}} @@ -12,9 +12,13 @@ The {{KW|SYSTEM}} statement immediately closes a program and in DOS and can avoi ''Usage:'' * This command should be used to close a program quickly instead of pausing with [[END]] or nothing at all. * A code can be added after the statement to send a value to the [[SHELL (function)]] or [[_SHELLHIDE]] function in another module. -* If a program BAS module is run from the IDE, stopped by Ctrl-Break or an error occurs the QB program will exit to the [[IDE]]. -* In '''QB64''' SYSTEM ends the program and closes the window immediately. The last screen image may not be displayed. +* SYSTEM ends the program and closes the window immediately. The last screen image may not be displayed. + + + +''Qbasic or QuickBasic:'' * '''Qbasic BAS files can be run like compiled programs without returning to the [[IDE]] when [[SYSTEM]] is used to [[END|end]] them!''' +* If a program BAS module is run from the IDE, stopped by Ctrl-Break or an error occurs the QB program will exit to the [[IDE]]. * To run a QuickBasic program without the [[IDE]] use the following [[DOS]] command line: {{text|QB.EXE /L /RUN filename.BAS|green}} diff --git a/internal/help/TIMER_(statement).txt b/internal/help/TIMER_(statement).txt index 6a9c73052..738b79a68 100644 --- a/internal/help/TIMER_(statement).txt +++ b/internal/help/TIMER_(statement).txt @@ -10,12 +10,13 @@ QB64 {{PageSyntax}} :::TIMER(''number%'') {ON|STOP|OFF|FREE} +{{Parameters}} +* ''number'' denotes a specific numbered timer event in '''QB64 only'''. QB64 can run many timer events at once including the base timer. * TIMER ON enables event trapping of an [[ON TIMER (n)]] statement. While enabled, a check is made after every code statement to see if the specified time has elapsed and the ON TIMER [[GOSUB]] (or [[SUB]] in QB64) procedure is executed. * TIMER STOP disables timer event trapping. When an event occurs while stopped, it is remembered. If timer events are turned back on later, any remembered events are immediately executed. * TIMER OFF turns timer event trapping completely off and no subsequent events are remembered. <center>'''QB64 only'''</center> -* ''number'' denotes a specific numbered timer event in '''QB64 only'''. QB64 can run many timer events at once including the base timer. * Get a TIMER number from [[_FREETIMER]] ONLY except when the base timer(no number or 0) is used. Use specific variables or an array to hold each event number value for later reference. * If the TIMER number is omitted or 0, the TIMER used is the base timer. * Specific TIMER events can be enabled, suspended, turned off or freed using [[TIMER (statement)|TIMER(n)]] ON, STOP, OFF or FREE. diff --git a/internal/help/TROFF.txt b/internal/help/TROFF.txt index 188ce806a..92107c997 100644 --- a/internal/help/TROFF.txt +++ b/internal/help/TROFF.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The {{KW|TROFF}} statement turns off line number tracing. @@ -6,7 +12,7 @@ The {{KW|TROFF}} statement turns off line number tracing. {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * When line number tracing is on, the line numbers of statements are output immediately before they are executed. * Use {{KW|TRON}} to turn on line number tracing. * Line number tracing only has an effect when programs are compiled with debugging code (BC.EXE /D). diff --git a/internal/help/TRON.txt b/internal/help/TRON.txt index f015c044d..8bcbdcff4 100644 --- a/internal/help/TRON.txt +++ b/internal/help/TRON.txt @@ -1,3 +1,9 @@ +''This page is maintained for historic purposes. The keyword is not supported in QB64.'' + + +---- + + The {{KW|TRON}} statement turns on line number tracing. @@ -6,7 +12,7 @@ The {{KW|TRON}} statement turns on line number tracing. {{PageDescription}} -*'''[[Keywords currently not supported by QB64|Currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|Not supported in QB64.]]''' * When line number tracing is on, the line numbers of statements are output immediately before they are executed. * Use {{KW|TROFF}} to turn off line number tracing. * Line number tracing only has an effect when programs are compiled with debugging code (<tt>BC.EXE /D</tt>). diff --git a/internal/help/UCASE$.txt b/internal/help/UCASE$.txt index 6e5a36c41..5ba54a096 100644 --- a/internal/help/UCASE$.txt +++ b/internal/help/UCASE$.txt @@ -1,15 +1,16 @@ -The '''UCASE$''' function changes the lowercase letters of a {{KW|STRING}} to uppercase. +The [[UCASE$]] function outputs an all-uppercase version of a [[STRING]]. {{PageSyntax}} -:''result$'' = '''UCASE$('''{{Parameter|text$}}''')''' +:{{Parameter|result$}} = [[UCASE$]]({{Parameter|text$}}) {{PageDescription}} -* Used to guarantee that all alphabetical letters in a [[STRING]] are capitalized. -* Will not affect non alphabet string characters. Will not shift key characters. +* Used to guarantee that all alphabetical characters in a [[STRING]] are capitalized. +* Does not affect non-alphabetical characters. +{{PageExamples}} ''Example:'' The following code guarantees that all letter key entries are capitalized: {{CodeStart}}{{Cl|PRINT}} "Do you want to continue? (y/n)" diff --git a/internal/help/WHILE...WEND.txt b/internal/help/WHILE...WEND.txt index e2208b322..2c9957d23 100644 --- a/internal/help/WHILE...WEND.txt +++ b/internal/help/WHILE...WEND.txt @@ -43,6 +43,7 @@ The {{KW|WHILE...WEND}} statement is used to repeat a block of statements while * [[DO...LOOP]] * [[FOR...NEXT]] * [[UNTIL]] (condition) +* [[_CONTINUE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/WIDTH.txt b/internal/help/WIDTH.txt index fe9114bc1..fecdcc191 100644 --- a/internal/help/WIDTH.txt +++ b/internal/help/WIDTH.txt @@ -1,4 +1,4 @@ -The {{KW|WIDTH}} statement changes the text dimensions of certain {{KW|SCREEN (statement)|SCREEN}} modes or printers using the {{KW|WIDTH}} {{KW|LPRINT}} statement. +The {{KW|WIDTH}} statement changes the text dimensions of certain {{KW|SCREEN (statement)|SCREEN}} modes. ''SCREEN'' {{PageSyntax}} @@ -7,14 +7,12 @@ The {{KW|WIDTH}} statement changes the text dimensions of certain {{KW|SCREEN (s ''File'' {{PageSyntax}} ::: '''WIDTH''' {'''''file_number''''' | '''''device'''''}, '''''columnwidth%''''' -''LPRINT'' {{PageSyntax}} +''LPRINT'' {{PageSyntax}} (not supported in QB64): ::: '''WIDTH LPRINT ''columnwidth%''''' {{Parameters}} * When parameters are not specified, columns defaults to 80 with 25 (30 in [[SCREEN]] 11 or 12) rows. -* Devices opened with an [[OPEN]] statement include LPT1 and CONS in Qbasic ONLY. -* Only the column width(default 80) can be specified in the file or [[LPRINT]] syntax. ''Usage:'' @@ -26,7 +24,12 @@ The {{KW|WIDTH}} statement changes the text dimensions of certain {{KW|SCREEN (s :* SCREEN 11 and 12 can use 80 columns and 30 or 60 rows. Default is WIDTH 80, 30 fullscreen. * '''QB64''' can alter all [[SCREEN]] mode widths and heights which may also affect text or [[_FONT]] block sizes. * '''Note:''' WIDTH changes may change screen color settings in QBasic. Use [[PALETTE]] to reset to default colors. -*'''[[Keywords currently not supported by QB64|WIDTH LPRINT is currently NOT supported in QB64!]]''' +*'''[[Keywords currently not supported by QB64|WIDTH LPRINT is not supported in QB64.]]''' + + +''Qbasic or QuickBasic:'' +* Devices opened with an [[OPEN]] statement include LPT1 and CONS in Qbasic ONLY. +* Only the column width(default 80) can be specified in the file or [[LPRINT]] syntax. {{PageSeeAlso}} diff --git a/internal/help/XOR.txt b/internal/help/XOR.txt index c05543c18..564493398 100644 --- a/internal/help/XOR.txt +++ b/internal/help/XOR.txt @@ -43,7 +43,7 @@ ByteValue% = {{Cl|INP}}(address%) ''See also:'' -* [[AND]], [[OR]] +* [[AND]], [[OR]] {{text|(logical operators)}} * [[Binary]], [[Boolean]] diff --git a/internal/help/_ACOS.txt b/internal/help/_ACOS.txt index a1b23580d..a2159bbec 100644 --- a/internal/help/_ACOS.txt +++ b/internal/help/_ACOS.txt @@ -1,18 +1,21 @@ {{DISPLAYTITLE:_ACOS}} -The '''_ACOS''' function returns the angle measured in radians based on an input [[COS]]ine value ranging from -1 to 1. +The [[_ACOS]] function returns the angle measured in radians based on an input [[COS]]ine value ranging from -1 to 1. -{{PageSyntax}} -::::: radian_angle! = _ACOS(''cosine_value!'') - +{{PageSyntax}} +: {{Parameter|radian_angle!}} = [[_ACOS]]({{Parameter|cosine_value!}}) +{{PageDescription}} * The ''cosine_value!'' must be measured >= -1 and <= 1, or an error will be generated. (PRINT _ACOS(1.2) would give the result of -1.#IND, which is basically QB64's way of telling us that the number doesn't exist, much like 1/0 would.) * ARCCOSINE is the inverse function of [[COS]]ine, which lets us turn a [[COS]]ine value back into an angle. * Note: Due to rounding with floating point math, the _ACOS may not always give a perfect match for the COS angle which generated this. You can reduce the number of rounding errors by increasing the precision of your calculations by using [[DOUBLE]] or [[_FLOAT]] precision variables instead of [[SINGLE]]. -* ''(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.)'' + +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Converting a radian angle to its COSine and using that value to find the angle in degrees again using _ACOS: {{CodeStart}} '' '' {{Cl|DEFDBL}} A-Z @@ -35,12 +38,12 @@ Notice, A is the Angle in Radians. If we convert it to degrees, we discover the {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]] {{text|(degree to gradient}}, [[_D2R]] {{text|(degree to radian)}} * [[_G2D]] {{text|(gradient to degree)}}, [[_G2R]] {{text|(gradient to degree}} * [[_R2D]] {{text|(radian to degree)}}, [[_R2G]] {{text|(radian to gradient}} * [[COS]] {{text|(cosine)}}, [[SIN]] {{text|(sine)}}, [[TAN]] {{text|(tangent)}} -* [[_ACOS]] {{text|(arc cosine)}}, [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} +* [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} * [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} * [[_ATAN2]] {{text|(Compute arc tangent with two parameters)}} * [[_HYPOT]] {{text|(hypotenuse)}} diff --git a/internal/help/_ACOSH.txt b/internal/help/_ACOSH.txt index d7f7c8080..4a4c968e6 100644 --- a/internal/help/_ACOSH.txt +++ b/internal/help/_ACOSH.txt @@ -1,21 +1,17 @@ {{DISPLAYTITLE:_ACOSH}} -The '''_ACOSH''' returns the nonnegative arc hyperbolic cosine of x, expressed in radians. +The [[_ACOSH]] returns the nonnegative arc hyperbolic cosine of {{Parameter|x!}}, expressed in radians. -{{PageSyntax}} -::::: return_value! = _ACOSH(''x!'') +{{PageSyntax}} +: {{Parameter|return_value!}} = [[_ACOSH]]({{Parameter|x!}}) - - - - -''See also:'' +{{PageSeeAlso}} * [[_D2G]] {{text|(degree to gradient}}, [[_D2R]] {{text|(degree to radian)}} * [[_G2D]] {{text|(gradient to degree)}}, [[_G2R]] {{text|(gradient to degree)}} * [[_R2D]] {{text|(radian to degree)}}, [[_R2G]] {{text|(radian to gradient)}} * [[COS]] {{text|(cosine)}}, [[SIN]] {{text|(sine)}}, [[TAN]] {{text|(tangent)}} * [[_ACOS]] {{text|(arc cosine)}}, [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} -* [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} +* [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} * [[_ATAN2]] {{text|(Compute arc tangent with two parameters)}} * [[_HYPOT]] {{text|(hypotenuse)}} *[[Mathematical Operations]] diff --git a/internal/help/_ALPHA.txt b/internal/help/_ALPHA.txt index 8f954d494..62b6c9354 100644 --- a/internal/help/_ALPHA.txt +++ b/internal/help/_ALPHA.txt @@ -1,22 +1,23 @@ {{DISPLAYTITLE:_ALPHA}} -The {{KW|_ALPHA}} function returns the alpha channel transparency level of a color value used on a screen page or image. +The [[_ALPHA]] function returns the alpha channel transparency level of a color value used on a screen page or image. {{PageSyntax}} -:{{Parameter|result&}} = {{KW|_ALPHA}}({{Parameter|colour~&}} [, {{Parameter|imageHandle&}}]) +:{{Parameter|result&}} = [[_ALPHA]]({{Parameter|color~&}} [, {{Parameter|imageHandle&}}]) {{PageDescription}} * If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page. Invalid handles will create [[ERROR Codes|Illegal function call]] errors. -* [[_NEWIMAGE]] 32 bit [[SCREEN]] modes will always use an [[_UNSIGNED]] [[LONG]] ''colour'' value. +* [[_NEWIMAGE]] 32 bit [[SCREEN]] modes will always use an [[_UNSIGNED]] [[LONG]] ''color~&'' value. ** Color values that are set as a [[_CLEARCOLOR]] always have an alpha level of 0 (transparent). -** [[_SETALPHA]] can set any alpha level from 0 or fully transparent to 255 or opaque. +** [[_SETALPHA]] can set any alpha level from 0 (or fully transparent) to 255 (or opaque). ** Normal color values that are set by [[_RGB]] or [[_RGB32]] always have an alpha level of 255(opaque). * In 4 (16 color) or 8 (256 color) bit palette screens the function will always return 255. *[[_RED32]], [[_GREEN32]], [[_BLUE32]] and [[_ALPHA32]] are all equivalent to [[_RED]], [[_GREEN]], [[_BLUE]] and [[_ALPHA]] but they are highly optimized and only accept a 32-bit color (B8:G8:R8:A8). Using them (opposed to dividing then ANDing 32-bit color values manually) makes code easy to read. -* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque!''' +* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque.''' +{{PageExamples}} ''Example 1:'' Alpha transparency levels are always 255 in 4 or 8 bit screen modes. {{CodeStart}} '' '' {{Cl|SCREEN}} 13 diff --git a/internal/help/_ALPHA32.txt b/internal/help/_ALPHA32.txt index bff12eb1c..caa1650d8 100644 --- a/internal/help/_ALPHA32.txt +++ b/internal/help/_ALPHA32.txt @@ -1,24 +1,24 @@ {{DISPLAYTITLE:_ALPHA32}} -The [[_ALPHA32]] function returns the alpha transparency level of a 32 bit color value only. +The [[_ALPHA32]] function returns the alpha transparency level of a 32 bit color value. {{PageSyntax}} -:{{Parameter|alpha&}} = '''_ALPHA32({{Parameter|colour32~&}})''' - +:{{Parameter|alpha&}} = [[_ALPHA32]]({{Parameter|color32~&}})''' {{Parameters}} -* {{Parameter|colour32&}} is the [[_UNSIGNED]] [[LONG]] 32 bit color value used to retrieve the alpha level. +* {{Parameter|color32&}} is the [[_UNSIGNED]] [[LONG]] 32 bit color value used to retrieve the alpha level. ** Color values that are set as a [[_CLEARCOLOR]] always have an alpha level of 0 (transparent). -** [[_SETALPHA]] can set any alpha level from 0 or fully transparent to 255 or opaque. -** Normal color values that are set by [[_RGB]] or [[_RGB32]] always have an alpha level of 255(opaque). +** [[_SETALPHA]] can set any alpha level from 0 (or fully transparent) to 255 (or opaque). +** Normal color values that are set by [[_RGB]] or [[_RGB32]] always have an alpha level of 255 (opaque). -''Usage:'' -* In 4(16 color) or 8(256 color) bit palette screens the function will return 0. +{{PageDescription}} +* In 4-bit (16 colors) or 8-bit (256 colors) palette screens the function will return 0. * [[_RED32]], [[_GREEN32]], [[_BLUE32]] and [[_ALPHA32]] are all equivalent to [[_RED]], [[_GREEN]], [[_BLUE]] and [[_ALPHA]] but they are highly optimized and only accept a 32-bit color (RGBA) value. Using these in your code (opposed to dividing then ANDing 32-bit color values) makes code easy to read. * '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque!''' +{{PageExamples}} ''Example:'' Finding the alpha transparency level in a 32 bit screen using an [[_RGBA]] [[_UNSIGNED]] [[LONG]] color value. {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) diff --git a/internal/help/_ASIN.txt b/internal/help/_ASIN.txt index c4831f44a..b3c85cd3c 100644 --- a/internal/help/_ASIN.txt +++ b/internal/help/_ASIN.txt @@ -1,18 +1,22 @@ {{DISPLAYTITLE:_ASIN}} -The '''_ASIN''' function returns the angle measured in radians based on an input [[SIN]]e value ranging from -1 to 1. +The [[_ASIN]] function returns the angle measured in radians based on an input [[SIN]]e value ranging from -1 to 1. -{{PageSyntax}} -::::: radian_angle! = _ASIN(''sine_value!'') +{{PageSyntax}} +: {{Parameter|radian_angle!}} = [[_ASIN]]({{Parameter|sine_value!}}) -* The ''sine_value!'' must be measured >= -1 and <= 1, or else it will generate a return value of -1.#IND, which is basically QB64's way of telling us that the number doesn't exist. +{{PageDescription}} +* The {{Parameter|sine_value!}} must be measured >= -1 and <= 1, or else it will generate a return value of '''-1.#IND''', which is basically QB64's way of telling us that the number doesn't exist. * ARCSINE is the inverse function of [[SIN]]e, and turns a [[SIN]]e value back into an angle. -* Note: Due to rounding with floating point math, the _ASIN may not always give a perfect match for the SIN angle which generated this. You can reduce the number of rounding errors by increasing the precision of your calculations by using [[DOUBLE]] or [[_FLOAT]] precision variables instead of [[SINGLE]]. - -* ''(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.)'' +* Note: Due to rounding with floating point math, the [[_ASIN]] may not always give a perfect match for the [[SIN]] angle which generated this. You can reduce the number of rounding errors by increasing the precision of your calculations by using [[DOUBLE]] or [[_FLOAT]] precision variables instead of [[SINGLE]]. +==Availability== +* '''Version 1.000 and up''' + + +{{PageExamples}} ''Example:'' Converting a radian angle to its SINe and using that value to find the angle in degrees again using _ASIN: {{CodeStart}} '' '' {{Cl|DEFDBL}} A-Z @@ -35,12 +39,12 @@ Notice, A is the Angle in Radians. If we convert it to degrees, we discover the {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]] {{text|(degree to gradient}}, [[_D2R]] {{text|(degree to radian)}} * [[_G2D]] {{text|(gradient to degree)}}, [[_G2R]] {{text|(gradient to degree}} * [[_R2D]] {{text|(radian to degree)}}, [[_R2G]] {{text|(radian to gradient}} * [[COS]] {{text|(cosine)}}, [[SIN]] {{text|(sine)}}, [[TAN]] {{text|(tangent)}} -* [[_ACOS]] {{text|(arc cosine)}}, [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} +* [[_ACOS]] {{text|(arc cosine)}}, [[ATN]] {{text|(arc tangent)}} * [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} * [[_ATAN2]] {{text|(Compute arc tangent with two parameters)}} * [[_HYPOT]] {{text|(hypotenuse)}} diff --git a/internal/help/_ASINH.txt b/internal/help/_ASINH.txt index 98f8e0938..fd089883e 100644 --- a/internal/help/_ASINH.txt +++ b/internal/help/_ASINH.txt @@ -1,21 +1,18 @@ {{DISPLAYTITLE:_ASINH}} -The '''_ASINH''' returns the arc hyperbolic sine of x, expressed in radians. +The [[_ASINH]] returns the arc hyperbolic sine of x, expressed in radians. -{{PageSyntax}} -::::: return_value! = _ASINH(''x!'') +{{PageSyntax}} +: {{Parameter|return_value!}} = [[_ASINH]]({{Parameter|x!}}) - - - -''See also:'' +{{PageSeeAlso}} * [[_D2G]] {{text|(degree to gradient}}, [[_D2R]] {{text|(degree to radian)}} * [[_G2D]] {{text|(gradient to degree)}}, [[_G2R]] {{text|(gradient to degree)}} * [[_R2D]] {{text|(radian to degree)}}, [[_R2G]] {{text|(radian to gradient)}} * [[COS]] {{text|(cosine)}}, [[SIN]] {{text|(sine)}}, [[TAN]] {{text|(tangent)}} * [[_ACOS]] {{text|(arc cosine)}}, [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} -* [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} +* [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} * [[_ATAN2]] {{text|(Compute arc tangent with two parameters)}} * [[_HYPOT]] {{text|(hypotenuse)}} *[[Mathematical Operations]] diff --git a/internal/help/_ATAN2.txt b/internal/help/_ATAN2.txt index 4e36dc30a..31fac599d 100644 --- a/internal/help/_ATAN2.txt +++ b/internal/help/_ATAN2.txt @@ -1,18 +1,17 @@ {{DISPLAYTITLE:_ATAN2}} -The '''_ATAN2''' function returns the radian angle between the positive x-axis of a plane and the point given by the coordinates (x, y). +The [[_ATAN2]] function returns the radian angle between the positive x-axis of a plane and the point given by the coordinates (x, y). {{PageSyntax}} -::: angle! = '''_ATAN2(''' ''y'', ''x''''')''' +: {{Parameter|angle!}} = [[_ATAN2]]({{Parameter|y}}, {{Parameter|x}}) {{Parameters}} -* ''y'' is the vertical axis position(row) as a positive, zero or negative floating point value. -* ''x'' is the horizontal axis position(column) as a positive, zero or negative floating point value. +* {{Parameter|y}} is the vertical axis position (row) as a positive, zero or negative floating point value. +* {{Parameter|x}} is the horizontal axis position (column) as a positive, zero or negative floating point value. {{PageDescription}} - * The [[DOUBLE]] radian angle returned is '''positive''' for upper row values where y > 0. ::* _ATAN2(y, x) = [[ATN]](y# / x#) when x > 0 ::* _ATAN2(y, x) = [[ATN]](y# / x#) + [[_PI]] when x < 0 @@ -26,7 +25,7 @@ The '''_ATAN2''' function returns the radian angle between the positive x-axis o {{PageErrors}} -* Note: With [[ATN]](y / x), x can never be 0 as that would create a Division by Zero [[ERROR Codes|error]] 11 or #IND. +* With [[ATN]](y / x), x can never be 0 as that would create a Division by Zero [[ERROR Codes|error]] 11 or #IND. {{PageSeeAlso}} diff --git a/internal/help/_ATANH.txt b/internal/help/_ATANH.txt index 4d321e880..d3d417eba 100644 --- a/internal/help/_ATANH.txt +++ b/internal/help/_ATANH.txt @@ -1,21 +1,18 @@ {{DISPLAYTITLE:_ATANH}} -The '''_ATANH''' returns the arc hyperbolic tangent of x, expressed in radians. +The [[_ATANH]] returns the arc hyperbolic tangent of {{Parameter|x!}}, expressed in radians. -{{PageSyntax}} -::::: return_value! = _ATANH(''x!'') +{{PageSyntax}} +: {{Parameter|return_value!}} = [[_ATANH]]({{Parameter|x!}}) - - - -''See also:'' +{{PageSeeAlso}} * [[_D2G]] {{text|(degree to gradient}}, [[_D2R]] {{text|(degree to radian)}} * [[_G2D]] {{text|(gradient to degree)}}, [[_G2R]] {{text|(gradient to degree)}} * [[_R2D]] {{text|(radian to degree)}}, [[_R2G]] {{text|(radian to gradient)}} * [[COS]] {{text|(cosine)}}, [[SIN]] {{text|(sine)}}, [[TAN]] {{text|(tangent)}} * [[_ACOS]] {{text|(arc cosine)}}, [[_ASIN]] {{text|(arc sine)}}, [[ATN]] {{text|(arc tangent)}} -* [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}}, [[_ATANH]] {{text|(arc hyperbolic tangent)}} +* [[_ACOSH]] {{text|(arc hyperbolic cosine)}}, [[_ASINH]] {{text|(arc hyperbolic sine)}} * [[_ATAN2]] {{text|(Compute arc tangent with two parameters)}} * [[_HYPOT]] {{text|(hypotenuse)}} *[[Mathematical Operations]] diff --git a/internal/help/_AUTODISPLAY.txt b/internal/help/_AUTODISPLAY.txt index 4c90cdad7..2dce81426 100644 --- a/internal/help/_AUTODISPLAY.txt +++ b/internal/help/_AUTODISPLAY.txt @@ -1,18 +1,20 @@ {{DISPLAYTITLE:_AUTODISPLAY}} -The {{KW|_AUTODISPLAY}} statement enables the automatic display of the screen image changes previously disabled by {{KW|_DISPLAY}}. +The [[_AUTODISPLAY]] statement enables the automatic display of the screen image changes previously disabled by [[_DISPLAY]]. {{PageSyntax}} -:<code>{{KW|_AUTODISPLAY}}</code> +:[[_AUTODISPLAY]] {{PageDescription}} -* {{KW|_AUTODISPLAY}} is on by default and displays the screen at around 30 frames per second (normal vertical retrace speed). -* {{KW|_DISPLAY}} disables automatic graphic displays, but it also eliminates having to use PCOPY or page flipping when used correctly. Placing _DISPLAY after screen draws or other screen changes assures completion of the changes before they are displayed. The speed of QB64 code execution makes this a viable option. +* [[_AUTODISPLAY]] is on by default and displays the screen at around 30 frames per second (normal vertical retrace speed). +* [[_DISPLAY]] disables automatic graphic displays, but it also eliminates having to use PCOPY or page flipping when used correctly. Placing _DISPLAY after screen draws or other screen changes assures completion of the changes before they are displayed. The speed of QB64 code execution makes this a viable option. +* The [[_AUTODISPLAY (function)]] can be used to detect the current display behavior. {{PageSeeAlso}} -* {{KW|_DISPLAY}} +* [[_DISPLAY]] +* [[_AUTODISPLAY (function)]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_AXIS.txt b/internal/help/_AXIS.txt index b31db1d5b..f86ae407e 100644 --- a/internal/help/_AXIS.txt +++ b/internal/help/_AXIS.txt @@ -1,17 +1,18 @@ {{DISPLAYTITLE:_AXIS}} -The '''_AXIS''' function returns the relative position of a specified axis number on a controller device. +The [[_AXIS]] function returns the relative position of a specified axis number on a controller device. {{PageSyntax}} -::: move = _AXIS(''axis_number%'') +: {{Parameter|move!}} = [[_AXIS]]({{Parameter|axis_number%}}) * [[SINGLE]] values returned range between -1 and 1 as maximums and 0 indicating minimum or axis center. * When the mouse is moved on the program screen, moves left or above center are negative while below or right are positive. * The ''axis_number'' must be a number which does not exceed the number of axis found by the [[_LASTAXIS]] function. -* '''The number of [[_DEVICES]] MUST be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTAXIS]]!''' +* '''The number of [[_DEVICES]] must be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTAXIS]].''' +{{PageExamples}} ''Example:'' Reading multiple controller device buttons, axis and wheels. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|_DEVICES}} @@ -40,7 +41,7 @@ The '''_AXIS''' function returns the relative position of a specified axis numbe : ''Note:'' When there is no device control to read, a [[FOR...NEXT|FOR]] n = 1 TO 0 loop will not run thus avoiding a control function read error. -''See also:'' +{{PageSeeAlso}} * [[_LASTWHEEL]], [[_LASTBUTTON]], [[_LASTAXIS]] * [[_WHEEL]], [[_BUTTON]], [[_BUTTONCHANGE]] * [[_DEVICE$]], [[_DEVICES]] diff --git a/internal/help/_BACKGROUNDCOLOR.txt b/internal/help/_BACKGROUNDCOLOR.txt index 19f3821de..f6edbb51f 100644 --- a/internal/help/_BACKGROUNDCOLOR.txt +++ b/internal/help/_BACKGROUNDCOLOR.txt @@ -1,18 +1,31 @@ {{DISPLAYTITLE:_BACKGROUNDCOLOR}} -The {{KW|_BACKGROUNDCOLOR}} function returns the current background color. +The [[_BACKGROUNDCOLOR]] function returns the current background color. {{PageSyntax}} -:{{Parameter|BGcolor&}} = {{KW|_BACKGROUNDCOLOR}} +:{{Parameter|BGcolor&}} = [[_BACKGROUNDCOLOR]] {{PageDescription}} * Use it to get the current background color to restore later in a program. -* Will return the closest attribute value of the background color +* Returns the closest attribute value of the background color. -''Example:'' Storing a background color for later use. +{{PageExamples}} +''Example 1:'' Storing a background color for later use. +{{CodeStart}} '' '' +{{Cl|SCREEN}} 0 +{{Cl|COLOR}} 1, 3 +{{Cl|CLS}} +BG% = {{Cl|_BACKGROUNDCOLOR}} +{{Cl|PRINT}} BG% +{{CodeEnd}} +{{BlueStart}}3 +{{BlueEnd}} + + +''Example 2:'' Understanding the function output {{CodeStart}} '' '' {{Cl|SCREEN}} 0 {{Cl|COLOR}} 1, 11 diff --git a/internal/help/_BIT.txt b/internal/help/_BIT.txt index 53f12cb05..c54c4735e 100644 --- a/internal/help/_BIT.txt +++ b/internal/help/_BIT.txt @@ -1,25 +1,23 @@ {{DISPLAYTITLE:_BIT}} -The '''_BIT''' datatype can return only values of 0 (bit off) and -1 (bit on). +The [[_BIT]] datatype can return only values of 0 (bit off) and -1 (bit on). {{PageSyntax}} -:: [[DIM]] variable AS [_UNSIGNED] '''_BIT''' [* numberofbits] +: [[DIM]] {{Parameter|variable}} [[AS]] [[[_UNSIGNED]]] [[_BIT]] [* {{Parameter|numberofbits}}] + +: [[_DEFINE]] {{Parameter|Letter}}[{{Parameter|-Range}}|,...] [[AS]] [[[_UNSIGNED]]] [[_BIT]] [* {{Parameter|numberofbits}}] -:: [[_DEFINE]] Letter[-Range|,...] AS [_UNSIGNED] '''_BIT''' [* numberofbits] - - -''More information:'' - -* An [[_UNSIGNED]] _BIT can hold 0 or 1 instead of 0 and -1, if you set the numberofbits you can hold larger values depending on the number of bits you have set (_BIT * 8 can hold the same values as [[_BYTE]] for example) and the information below is comprimised if setting any number of bits other than 1. +{{PageDescription}} +* An [[_UNSIGNED]] _BIT can hold 0 or 1 instead of 0 and -1, if you set the numberofbits you can hold larger values depending on the number of bits you have set (_BIT * 8 can hold the same values as [[_BYTE]] for example) and the information below is compromised if setting any number of bits other than 1. * If you set the variable to any other number then the least significant bit of that number will be set as the variables number, if the bit is 1 (on) then the variable will be -1 and if the bit is 0 (off) then the variable will be 0. *The least significant bit is the last bit on a string of bits (11111) since that bit will only add 1 to the value if set. The most significant bit is the first bit on a string of bits and changes the value more dramatically (significantly) if set on or off. *The _BIT datatype can be succesfully used as a [[Boolean]] (TRUE or FALSE) and it requires minimal amount of memory (the lowest amount possible actually, one byte can hold 8 bits, if you want to use bits in order to decrease memory usage, use them as arrays as a _BIT variable by itself allocates 4 bytes - DIM bitarray(800) AS _BIT uses 100 bytes). * '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' -* '''[[Keywords_currently_not_supported_by_QB64|_BIT is not currently supported in User Defined TYPES!]]''' +* '''[[Keywords_currently_not_supported_by_QB64|_BIT is not supported in User Defined TYPES.]]''' Use a [[_BYTE]] and assign up to 8 bit values as shown below. -*'''Suffix Symbols''' The bit type suffix used is below the shifted tilde key! '''NOT an apostrophy'''! Foreign keyboards may not have the ´ key. Try [[CHR$]](96). +*'''Suffix Symbols''' The [[_BIT]] type suffix used is below the grave accent (`), usually located under the tilde (~) key, not an apostrophe! Foreign keyboards may not have the ` key. Try [[CHR$]](96). :You can define a bit on-the-fly by adding a ` after the variable, like this; variable` = -1 @@ -54,6 +52,7 @@ The '''_BIT''' datatype can return only values of 0 (bit off) and -1 (bit on). ::The HI byte's '''MSB''' is often called the '''sign''' bit! When all 16 of the integer binary bits are on, the decimal return is -1. +{{PageExamples}} ''Example:'' Shifting bits in a value. {{CodeStart}} '' '' n = 24 diff --git a/internal/help/_BLEND.txt b/internal/help/_BLEND.txt index 467c4f862..8fca011e6 100644 --- a/internal/help/_BLEND.txt +++ b/internal/help/_BLEND.txt @@ -1,19 +1,23 @@ {{DISPLAYTITLE:_BLEND}} -The _BLEND statement turns on 32 bit alpha blending for the current image or screen mode and is default. +The [[_BLEND]] statement turns on 32 bit alpha blending for an image or screen mode and is on by default. {{PageSyntax}} -: _BLEND [{{Parameter|imageHandle&}}] +: [[_BLEND]] [{{Parameter|imageHandle&}}] + +===Parameters=== +* {{Parameter|imageHandle&}} refers to an image in memory. If not specified, the current destination page (See [[_DEST]]) is affected. {{PageDescription}} * Alpha blending is on by default when loading a .PNG image to a 32-bit surface. -* Normally it is used to turn blending on after a previous {{KW|_DONTBLEND}} call. -* {{KW|_BLEND}} can only be used on 32-bit surfaces, otherwise it will produce the error [[ERROR Codes|Illegal Function Call]]. -* '''Note: [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit!''' -* '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +* Normally it is used to turn blending on after a previous [[_DONTBLEND]] call. +* [[_BLEND]] can only be used on 32-bit surfaces, otherwise it will produce the error [[ERROR Codes|Illegal Function Call]]. +* '''Note: [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit.''' +* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +{{PageExamples}} ''Example:'' {{CodeStart}} {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) @@ -130,7 +134,7 @@ m& = {{Cl|POINT}}(303, 302) {{PageSeeAlso}} -* {{KW|_DONTBLEND}}, {{KW|_BLEND (function)}} +* [[_DONTBLEND]], [[_BLEND (function)]] * [[Images]] diff --git a/internal/help/_BLEND_(function).txt b/internal/help/_BLEND_(function).txt index 453103838..db793b177 100644 --- a/internal/help/_BLEND_(function).txt +++ b/internal/help/_BLEND_(function).txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_BLEND (function)}} -The {{KW|_BLEND (function)|_BLEND}} function returns enabled or disabled for the current window or a specified image handle when 32 bit. +The [[_BLEND (function)|_BLEND]] function returns enabled or disabled for the current window or a specified image handle when 32 bit. {{PageSyntax}} -:''result%'' = {{KW|_BLEND (function)|_BLEND}} [({{Parameter|imageHandle&}})] +:{{Parameter|result%}} = [[_BLEND (function)|_BLEND]] [({{Parameter|imageHandle&}})] {{PageDescription}} -* _BLEND returns -1 if enabled or 0 if disabled by {{KW|_DONTBLEND}} statement. -* '''Note: [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit!''' +* _BLEND returns -1 if enabled or 0 if disabled by [[_DONTBLEND]] statement. +* '''Note: [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit.''' {{PageSeeAlso}} -* {{KW|_DONTBLEND}}, {{KW|_BLEND}} +* [[_DONTBLEND]], [[_BLEND]] * [[Images]] diff --git a/internal/help/_BLUE.txt b/internal/help/_BLUE.txt index 6e2958b1e..3984104e1 100644 --- a/internal/help/_BLUE.txt +++ b/internal/help/_BLUE.txt @@ -3,7 +3,7 @@ The [[_BLUE]] function returns the palette intensity or the blue component inten {{PageSyntax}} -:: blueintensity% = '''_BLUE('''{{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]''')''' +: {{Parameter|blueintensity&}} = [[_BLUE]]({{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]) {{PageDescription}} @@ -14,12 +14,12 @@ The [[_BLUE]] function returns the palette intensity or the blue component inten * If {{Parameter|imageHandle&}} is not specified, it is assumed to be the current write page. * If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error will occur. * If {{Parameter|rgbaColorIndex&}} is outside the range of valid indexes for a given image mode, an [[ERROR Codes|illegal function call]] error occurs. -* Uses index parameters passed by the {{KW|_RGB}}, {{KW|_RGBA}}, {{KW|_RGB32}} or {{KW|_RGBA32}} funtions. +* Uses index parameters passed by the [[_RGB]], [[_RGBA]], [[_RGB32]] or [[_RGBA32]] funtions. * An image handle is optional. -''See Example:'' -* [[POINT]] +{{PageExamples}} +* See the example for [[POINT]]. {{PageSeeAlso}} diff --git a/internal/help/_BLUE32.txt b/internal/help/_BLUE32.txt index f65b474a2..7cf1b4453 100644 --- a/internal/help/_BLUE32.txt +++ b/internal/help/_BLUE32.txt @@ -1,24 +1,24 @@ {{DISPLAYTITLE:_BLUE32}} -The [[_BLUE32]] function ALWAYS returns the blue component intensity of a 32-bit image ot surface color. +The [[_BLUE32]] function returns the blue component intensity of a 32-bit image or surface color. {{PageSyntax}} -:: blue32color& = '''_BLUE32('''{{Parameter|rgbaColor&}}''')''' +: {{Parameter|blue32color&}} = [[_BLUE32]]({{Parameter|rgbaColor&}}) {{PageDescription}} * {{Parameter|rgbaColor&}} is the 32-bit ''RGBA'' color value to retrieve the blue component intensity value from. -* ''RGBA'' color values are returned by the {{KW|_PALETTECOLOR (function)|_PALETTECOLOR}}, {{KW|POINT}}, {{KW|_RGB}}, {{KW|_RGB32}}, {{KW|_RGBA}} or {{KW|_RGBA32}} functions. -* [[LONG]] intensity values returned range from 0 (no intensity, not present) to 255 (full intensity). '''Do NOT use SINGLE variables!''' +* ''RGBA'' color values are returned by the [[_PALETTECOLOR (function)|_PALETTECOLOR]], [[POINT]], [[_RGB]], [[_RGB32]], [[_RGBA]] or [[_RGBA32]] functions. +* [[LONG]] intensity values returned range from 0 (no intensity, not present) to 255 (full intensity). -''See Example:'' -* [[POINT]] +{{PageExamples}} +* See the example for [[POINT]]. {{PageSeeAlso}} -* {{KW|_RED32}}, {{KW|_GREEN32}} -* {{KW|_RGB32}}, {{KW|_BLUE}} +* [[_RED32]], [[_GREEN32]] +* [[_RGB32]], [[_BLUE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_BUTTON.txt b/internal/help/_BUTTON.txt index 652d8cb44..d30905147 100644 --- a/internal/help/_BUTTON.txt +++ b/internal/help/_BUTTON.txt @@ -1,17 +1,19 @@ {{DISPLAYTITLE:_BUTTON}} -The '''_BUTTON''' function returns -1 when specified button number on a controller device is pressed. +The [[_BUTTON]] function returns -1 when specified button number on a controller device is pressed. {{PageSyntax}} -::: press = _BUTTON(''button_number%'') +: {{Parameter|press%%}} = [[_BUTTON]]({{Parameter|button_number%}}) +{{PageDescription}} * Values returned are -1 for a press and 0 when a button is released or not pressed. -* The ''button_number'' must be a number which does not exceed the number of buttons found by the [[_LASTBUTTON]] function. -* '''The number of [[_DEVICES]] MUST be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTBUTTON]]!''' +* The {{Parameter|button_number%}} must be a number which does not exceed the number of buttons found by the [[_LASTBUTTON]] function. +* '''The number of [[_DEVICES]] must be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTBUTTON]].''' * '''Note:''' The number 2 button is the center button in this device configuration. Center is also designated as [[_MOUSEBUTTON]](3). +{{PageExamples}} ''Example:'' Reading multiple controller device buttons, axis and wheels. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|_DEVICES}} @@ -40,7 +42,7 @@ The '''_BUTTON''' function returns -1 when specified button number on a controll : ''Note:'' When there is no device control to read, a [[FOR...NEXT|FOR]] n = 1 TO 0 loop will not run thus avoiding a control function read error. -''See also:'' +{{PageSeeAlso}} * [[_LASTWHEEL]], [[_LASTBUTTON]], [[_LASTAXIS]] * [[_AXIS]], [[_WHEEL]], [[_BUTTONCHANGE]] * [[_DEVICE$]], [[_DEVICES]] diff --git a/internal/help/_BUTTONCHANGE.txt b/internal/help/_BUTTONCHANGE.txt index b7c561507..f7a7de74d 100644 --- a/internal/help/_BUTTONCHANGE.txt +++ b/internal/help/_BUTTONCHANGE.txt @@ -1,17 +1,19 @@ {{DISPLAYTITLE:_BUTTONCHANGE}} -The '''_BUTTONCHANGE''' function returns -1 or 1 when a specified button number on a controller device has been pressed or released. +The [[_BUTTONCHANGE]] function returns -1 or 1 when a specified button number on a controller device has been pressed or released. {{PageSyntax}} -::: press = _BUTTONCHANGE(''button_number%'') +: {{Parameter|press%}} = [[_BUTTONCHANGE]]({{Parameter|button_number%}}) +{{PageDescription}} * Values returned are -1 for a press and 1 when a button is released. No press or release event returns zero. -* The ''button_number'' must be a number which does not exceed the number of buttons found by the [[_LASTBUTTON]] function. -* '''The number of [[_DEVICES]] MUST be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTBUTTON]]!''' +* The {{Parameter|button_number%}} must be a number which does not exceed the number of buttons found by the [[_LASTBUTTON]] function. +* '''The number of [[_DEVICES]] must be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTBUTTON]].''' * '''Note:''' The center mouse button is button number 2. Center can also be read using [[_MOUSEBUTTON]](3). +{{PageExamples}} ''Example:'' Reading multiple controller device buttons, axis and wheels. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|_DEVICES}} @@ -40,7 +42,7 @@ The '''_BUTTONCHANGE''' function returns -1 or 1 when a specified button number : ''Note:'' When there is no device control to read, a [[FOR...NEXT|FOR]] n = 1 TO 0 loop will not run thus avoiding a control function read error. -''See also:'' +{{PageSeeAlso}} * [[_LASTWHEEL]], [[_LASTBUTTON]], [[_LASTAXIS]] * [[_AXIS]], [[_WHEEL]], [[_BUTTON]] * [[_DEVICE$]], [[_DEVICES]] diff --git a/internal/help/_BYTE.txt b/internal/help/_BYTE.txt index f50ed784b..aaa2af1a3 100644 --- a/internal/help/_BYTE.txt +++ b/internal/help/_BYTE.txt @@ -1,17 +1,17 @@ {{DISPLAYTITLE:_BYTE}} -A '''_BYTE''' variable can hold signed variable values from -128 to 127 (one byte or 8 [[_BIT]]s). [[_UNSIGNED|Unsigned]] from 0 to 255. +A [[_BYTE]] variable can hold signed variable values from -128 to 127 (one byte or 8 [[_BIT]]s). [[_UNSIGNED|Unsigned]] from 0 to 255. {{PageSyntax}} -:{{KW|DIM}} byte {{KW|AS}} [{{KW|_UNSIGNED}}] {{KW|_BYTE}} +: [[DIM]] {{Parameter|byte}} [[AS]] [[[_UNSIGNED]]] [[_BYTE]] {{PageDescription}} * Signed _BYTE values can range from -128 to 127. -* [[_UNSIGNED]] _BYTEs can hold values from 0 to 255. {{KW|_UNSIGNED}} expands the range of positive values. +* [[_UNSIGNED]] _BYTEs can hold values from 0 to 255. [[_UNSIGNED]] expands the range of positive values. * Can be defined in a '''QB64''' [[_DEFINE]] statement using a starting letter range of variable names. * Also can be used in a subroutine parameter [[AS]] _BYTE variable definitions. -* Define a byte using the suffix %% after the variable name: variable%% = -54 +* Define a byte using the suffix %% after the variable name: {{Parameter|variable%%}} = -54 * Define an unsigned byte by adding the suffix ~%% after the variable name: variable~%% = 54 * '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' @@ -45,7 +45,7 @@ A '''_BYTE''' variable can hold signed variable values from -128 to 127 (one byt {{PageExamples}} -:How negative assignments affect the _UNSIGNED value returned by a byte(8 bits). +:How negative assignments affect the _UNSIGNED value returned by a byte (8 bits). {{CodeStart}} {{Cl|DIM}} unsig {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|_BYTE}} diff --git a/internal/help/_CEIL.txt b/internal/help/_CEIL.txt index d64ed6766..923fa387e 100644 --- a/internal/help/_CEIL.txt +++ b/internal/help/_CEIL.txt @@ -1,17 +1,20 @@ {{DISPLAYTITLE:_CEIL}} -The '''_CEIL''' function rounds a numeric value up to the next whole number or [[INTEGER]] value. +The [[_CEIL]] function rounds a numeric value up to the next whole number or [[INTEGER]] value. {{PageSyntax}} -:: result = [[_CEIL]](''expression'') +: {{Parameter|result}} = [[_CEIL]]({{Parameter|expression}}) -* [[_CEIL]] returns he smallest integral value that is greater than the numerical ''expression'' (as a floating-point value). +* [[_CEIL]] returns he smallest integral value that is greater than the numerical {{Parameter|expression}} (as a floating-point value). * This means that [[_CEIL]] rounds up for both positive and negative numbers. -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) + +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Displaying the rounding behavior of [[INT]], [[CINT]] and [[FIX]] vs [[_CEIL]]. {{CodeStart}} PRINT INT(2.5), CINT(2.5), FIX(2.5), _CEIL(2.5) @@ -22,7 +25,7 @@ PRINT INT(-2.5), CINT(-2.5), FIX(-2.5), _CEIL(-2.5) {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[INT]], [[FIX]] * [[CINT]], [[CLNG]], * [[CSNG]], [[CDBL]] diff --git a/internal/help/_CLEARCOLOR.txt b/internal/help/_CLEARCOLOR.txt index c094de091..76e4bc84a 100644 --- a/internal/help/_CLEARCOLOR.txt +++ b/internal/help/_CLEARCOLOR.txt @@ -1,11 +1,9 @@ {{DISPLAYTITLE:_CLEARCOLOR}} -The {{KW|_CLEARCOLOR}} statement sets a specific color to be treated as transparent when an image is later put (via [[_PUTIMAGE]]) onto another image. +The [[_CLEARCOLOR]] statement sets a specific color to be treated as transparent when an image is later put (via [[_PUTIMAGE]]) onto another image. {{PageSyntax}} -:::'''_CLEARCOLOR''' {''color&''|_NONE}[, {{Parameter|Dest_Handle&}}] - - +:[[_CLEARCOLOR]] {{{Parameter|color&}}|_NONE}[, {{Parameter|Dest_Handle&}}] {{Parameters}} * In color modes using a palette, {{Parameter|color&}} is the palette index of the new transparent color value or _NONE designates no clear colors. @@ -14,18 +12,19 @@ The {{KW|_CLEARCOLOR}} statement sets a specific color to be treated as transpar * If {{Parameter|Dest_Handle&}} is omitted, the destination is assumed to be the current write page. Zero can designate the current program screen. -''Usage:'' -* If {{Parameter|Dest_Handle&}} is an invalid handle, then an [[ERROR Codes|invalid handle]] error is returned. Check for bad handle values of -1 first! +{{PageDescription}} +* If {{Parameter|Dest_Handle&}} is an invalid handle, then an [[ERROR Codes|invalid handle]] error is returned. Check for bad handle values of -1 first. * In 32-bit color modes, it simply sets the Alpha to 0 for all pixels matching the specified color. * In the second syntax, transparency is disabled for color modes using a palette. -* '''Note:''' [[_SETALPHA]] can affect any _CLEARCOLOR alpha setting within the color range set! -* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque!''' +* '''Note:''' [[_SETALPHA]] can affect any _CLEARCOLOR alpha setting within the color range set. +* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque.''' +{{PageExamples}} ''Example 1:'' Using _CLEARCOLOR to "mask" the background color of an image. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 13 -img& = {{Cl|_LOADIMAGE}}("QB64bee.png") +img& = {{Cl|_LOADIMAGE}}("qb64_trans.png") {{Cl|_PUTIMAGE}} , img&, 0 'place actual image with background K$ = INPUT$(1) {{Cl|CLS}} , {{Cl|_RGB}}(255, 0, 0) 'clear screen with red background @@ -34,7 +33,7 @@ K$ = INPUT$(1) {{Cl|PRINT}} {{Cl|_CLEARCOLOR}}(img&) 'displays closest clear color attribute {{Cl|END}} '' '' {{CodeEnd}} -: ''Note:'' The ''QB64.PNG'' image can be downloaded here: [https://dl.dropbox.com/u/8440706/QB64bee.png QB64bee.png]. Right click and Save as ''QB64bee.PNG''. +: ''Note:'' The ''QB64.PNG'' image can be downloaded here: [http://www.qb64.net/qb64_trans.png qb64_trans.png]. Right click and Save as ''qb64_trans.png''. ''Example 2:'' Using a _CLEARCOLOR transparency with images created on a [[_NEWIMAGE]] page. Does not require an image file. @@ -57,7 +56,7 @@ redball = {{Cl|_NEWIMAGE}}(101, 101, 32) ' create a new image page mainscreen = {{Cl|_NEWIMAGE}}(640, 480, 32) ' Main Screen (viewable) {{Cl|SCREEN}} mainscreen {{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}} -Image1& = {{Cl|_LOADIMAGE}}("QB64bee.png") '<<<<<< any image with one background color to clear +Image1& = {{Cl|_LOADIMAGE}}("qb64_trans.png") '<<<<<< any image with one background color to clear {{Cl|IF...THEN|IF}} Image1& < -1 {{Cl|THEN}} 'check loaded image handle value before using! {{Cl|_SOURCE}} Image1& @@ -82,7 +81,7 @@ DO {{Cl|LOOP}} {{Cl|UNTIL}} a& = 0 {{Cl|END}} {{CodeEnd}} -:''Note:'' If the _CLEARCOLOR [https://dl.dropbox.com/u/8440706/QB64bee.png QB64bee.png] background was not put onto a separate page, [[_SETALPHA]] would display it also. +:''Note:'' If the _CLEARCOLOR [http://www.qb64.net/qb64_trans.png qb64_trans.png] background was not put onto a separate page, [[_SETALPHA]] would display it also. diff --git a/internal/help/_CLEARCOLOR_(function).txt b/internal/help/_CLEARCOLOR_(function).txt index 5ccbc058c..f502a684d 100644 --- a/internal/help/_CLEARCOLOR_(function).txt +++ b/internal/help/_CLEARCOLOR_(function).txt @@ -1,9 +1,9 @@ {{DISPLAYTITLE:_CLEARCOLOR (function)}} -The {{KW|_CLEARCOLOR (function)|_CLEARCOLOR}} function returns the current transparent color of an image or page. +The [[_CLEARCOLOR (function)|_CLEARCOLOR]] function returns the current transparent color of an image or page. {{PageSyntax}} -:''result&'' = {{KW|_CLEARCOLOR (function)|_CLEARCOLOR}} [{{Parameter|Source_Handle&}}] +:''result&'' = [[_CLEARCOLOR (function)|_CLEARCOLOR]] [{{Parameter|Source_Handle&}}] {{PageDescription}} @@ -13,7 +13,7 @@ The {{KW|_CLEARCOLOR (function)|_CLEARCOLOR}} function returns the current trans * In 32-bit color modes, zero is returned. * Returns the color that currently is transparent, or if no color is transparent -1 without error. * A [[_CLEARCOLOR]] statement can set the transparent color of an image or screen. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' {{PageSeeAlso}} diff --git a/internal/help/_CLIP.txt b/internal/help/_CLIP.txt index 6cc71ae42..f2da1c587 100644 --- a/internal/help/_CLIP.txt +++ b/internal/help/_CLIP.txt @@ -1,9 +1,9 @@ {{DISPLAYTITLE:_CLIP}} -The '''_CLIP''' option is used in a QB64 graphics [[PUT (graphics statement)|PUT]] to allow placement of an image partially off of the screen. +The [[_CLIP]] option is used in a QB64 graphics [[PUT (graphics statement)|PUT]] to allow placement of an image partially off of the screen. {{PageSyntax}} -:[[PUT (graphics statement)|PUT]] [STEP](column, row), ''image_array(start)''[, '''_CLIP'''] [{XOR|PSET|AND|OR|PRESET}][, ''omitcolor''] +:[[PUT (graphics statement)|PUT]] [[[STEP]]]({{Parameter|column, row}}), {{Parameter|image_array(start)}}[, [[_CLIP]]] [{XOR|PSET|AND|OR|PRESET}][, {{Parameter|omitcolor}}] {{PageDescription}} @@ -12,6 +12,7 @@ The '''_CLIP''' option is used in a QB64 graphics [[PUT (graphics statement)|PUT * [[GET (graphics statement)|GET]] can get portions of the images off screen in '''QB64'''. +{{PageExamples}} ''Example:'' Placing an image partially or fully offscreen. {{CodeStart}}'' '' {{Cl|DIM}} mypic(500) @@ -39,8 +40,6 @@ The '''_CLIP''' option is used in a QB64 graphics [[PUT (graphics statement)|PUT {{CodeEnd}} - - {{PageSeeAlso}} * [[PUT (graphics statement)]] * [[GET (graphics statement)]] diff --git a/internal/help/_CLIPBOARD$.txt b/internal/help/_CLIPBOARD$.txt index 6f228a61e..18e5e3560 100644 --- a/internal/help/_CLIPBOARD$.txt +++ b/internal/help/_CLIPBOARD$.txt @@ -3,7 +3,7 @@ The [[_CLIPBOARD$]] function returns the current Operating System's clipboard co {{PageSyntax}} -:''result$'' = _CLIPBOARD$ +:{{Parameter|result$}} = [[_CLIPBOARD$]] {{PageDescription}} @@ -12,6 +12,7 @@ The [[_CLIPBOARD$]] function returns the current Operating System's clipboard co * The clipboard can be used to copy, paste and communicate between running programs. +{{PageExamples}} ''Example 1:'' Passing a string value between two running programs no matter where they are located. : ''Program1:'' {{CodeStart}} '' '' @@ -136,6 +137,7 @@ K$ = {{Cl|UCASE$}}({{Cl|INPUT$}}(1)) {{PageSeeAlso}} * [[_CLIPBOARD$ (statement)]] +* [[_CLIPBOARDIMAGE (function)]], [[_CLIPBOARDIMAGE]] (statement) {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_CLIPBOARD$_(statement).txt b/internal/help/_CLIPBOARD$_(statement).txt index b172b0c7e..3d294c5c4 100644 --- a/internal/help/_CLIPBOARD$_(statement).txt +++ b/internal/help/_CLIPBOARD$_(statement).txt @@ -1,13 +1,13 @@ {{DISPLAYTITLE:_CLIPBOARD$ (statement)}} -The [[_CLIPBOARD$ (statement)|_CLIPBOARD$]] statement sets the {{KW|STRING}} value in the system clipboard. +The [[_CLIPBOARD$ (statement)|_CLIPBOARD$]] statement copies the [[STRING]] value into the system clipboard. {{PageSyntax}} -:{{KW|_CLIPBOARD$ (statement)|_CLIPBOARD$}} = {{Parameter|string_expression$}} +:[[_CLIPBOARD$ (statement)|_CLIPBOARD$]] = {{Parameter|string_expression$}} {{PageDescription}} -* {{Parameter|string_expression$}} is the string value sent to the clipboard. +* {{Parameter|string_expression$}} is the string value to be sent to the clipboard. * The string value will replace everything previously in the clipboard. * Assemble long text into one string variable value before using this statement. * Add CHR$(13) + CHR$(10) CRLF characters to move to a new clipboard line. @@ -16,6 +16,7 @@ The [[_CLIPBOARD$ (statement)|_CLIPBOARD$]] statement sets the {{KW|STRING}} val * The clipboard can be used to copy, paste and communicate between running programs. +{{PageExamples}} ''Example:'' Set 2 lines of text in the clipboard using a carriage return to end text lines {{CodeStart}} '' '' {{Cl|DIM}} CrLf AS {{Cl|STRING}} * 2 'define as 2 byte STRING @@ -33,8 +34,9 @@ This is line 2 {{PageSeeAlso}} -* {{KW|_CLIPBOARD$}} (function) -* {{KW|CHR$}}, {{KW|ASCII}} (code table) +* [[_CLIPBOARD$]] (function) +* [[_CLIPBOARDIMAGE (function)]], [[_CLIPBOARDIMAGE]] (statement) +* [[CHR$]], [[ASCII]] (code table) diff --git a/internal/help/_COMMANDCOUNT.txt b/internal/help/_COMMANDCOUNT.txt index c38c4efd6..69f68875c 100644 --- a/internal/help/_COMMANDCOUNT.txt +++ b/internal/help/_COMMANDCOUNT.txt @@ -3,15 +3,16 @@ The [[_COMMANDCOUNT]] function returns the number or arguments passed from the c {{PageSyntax}} -:::''result&'' = [[_COMMANDCOUNT]] +:{{Parameter|result&}} = [[_COMMANDCOUNT]] {{PageDescription}} * The function returns the number of arguments passed from the command line to a program when it's executed. * Arguments are spaced as separate numerical or text values. Spaced text inside of quotes is considered as one argument. -* In c, this function would generally be regarded as 'argc' when the main program is defined as the following: int main(int argc, char *argv[]) +* In C, this function would generally be regarded as 'argc' when the main program is defined as the following: '''int main(int argc, char *argv[])''' +{{PageExamples}} ''Example:'' The code below gets the number of parameters passed to our program from the command line with _COMMANDCOUNT: {{CodeStart}}limit = {{Cl|_COMMANDCOUNT}} {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} limit diff --git a/internal/help/_CONNECTED.txt b/internal/help/_CONNECTED.txt index 7e405acef..cf87cebcb 100644 --- a/internal/help/_CONNECTED.txt +++ b/internal/help/_CONNECTED.txt @@ -3,17 +3,19 @@ The [[_CONNECTED]] function returns the status of a TCP/IP connection handle. {{PageSyntax}} -:''result&'' = {{KW|_CONNECTED}}({{Parameter|connectionHandle&}}) +:{{Parameter|result&}} = [[_CONNECTED]]({{Parameter|connectionHandle&}}) {{PageDescription}} -* The handle can come from the {{KW|_OPENHOST}}, {{KW|OPENCLIENT}} or {{KW|_OPENCONNECTION}} QB64 TCP/IP functions. +* The handle can come from the [[_OPENHOST]], [[OPENCLIENT]] or [[_OPENCONNECTION]] QB64 TCP/IP functions. * Returns -1 if still connected or 0 if connection has ended/failed. -* Do not rely solely on this function to check for ending communication, -* Use "time-out" checking as well and {{KW|CLOSE}} any suspect connections. -* If this function indicates the handle is not connected, any unread messages can still be read using {{KW|INPUT (TCP/IP statement)|INPUT #}} or {{KW|GET (TCP/IP statement)|GET #}}. -* Even if this function indicates the handle is not connected, it is important to {{KW|CLOSE}} the connection anyway or important resources cannot be reallocated. +* Do not rely solely on this function to check for ending communication. +* Use "time-out" checking as well and [[CLOSE]] any suspect connections. +* If this function indicates the handle is not connected, any unread messages can still be read using [[INPUT (TCP/IP statement)|INPUT #]] or [[GET (TCP/IP statement)|GET #]]. +* Even if this function indicates the handle is not connected, it is important to [[CLOSE]] the connection anyway or important resources cannot be reallocated. + +{{PageExamples}} ''Snippet:'' Updating the [[_OPENHOST|_OPENHOST chat program example]] to manage the Users array when users are no longer connected. {{TextStart}} '' '' {{Cb|FOR...NEXT|FOR}} i = 1 {{Cb|TO}} numclients ' distribute incoming messages to all clients @@ -38,10 +40,10 @@ numclients = n: n = 0 '' '' {{PageSeeAlso}} -* {{KW|_OPENCONNECTION}} -* {{KW|_OPENHOST}} -* {{KW|_OPENCLIENT}} -* {{KW|_CONNECTIONADDRESS$}} +* [[_OPENCONNECTION]] +* [[_OPENHOST]] +* [[_OPENCLIENT]] +* [[_CONNECTIONADDRESS$]] * [[Downloading Files]] diff --git a/internal/help/_CONNECTIONADDRESS$.txt b/internal/help/_CONNECTIONADDRESS$.txt index a093bcfae..fe992b270 100644 --- a/internal/help/_CONNECTIONADDRESS$.txt +++ b/internal/help/_CONNECTIONADDRESS$.txt @@ -1,46 +1 @@ -{{DISPLAYTITLE:_CONNECTIONADDRESS$}} -The [[_CONNECTIONADDRESS$]] function returns a connected user's [[STRING]] IP address value. - - -{{PageSyntax}} -:''result$'' = {{KW|_CONNECTIONADDRESS$}}({{Parameter|connectionHandle&}}) - - -{{PageDescription}} -* The handle can come from the {{KW|_OPENHOST}}, {{KW|OPENCLIENT}} or {{KW|_OPENCONNECTION}} QB64 TCP/IP functions. -* For '''[[_OPENHOST|HOST]]s''': It may return "TCP/IP:8080:213.23.32.5" where 8080 is the port it is listening on and 213.23.32.5 is the global IP address which any computer connected to the internet could use to locate your computer. If a connection to the internet is unavailable or your firewall blocks it, it returns your 'local IP' address (127.0.0.1). You might like to store this address somewhere where other computers can find it and connect to your host. Dynamic IPs which can change will need to be updated. -* For '''[[_OPENCLIENT|CLIENT]]s''': It may return "TCP/IP:8080:213.23.32.5" where 8080 is the port it used to connect to the listening host and 213.23.32.5 is the IP address of the host name it resolved. -* For '''[[_OPENCONNECTION|CONNECTION]]s''' (from clients): It may return "TCP/IP:8080:34.232.321.25" where 8080 was the host listening port it connected to and 34.232.321.25 is the IP address of the client that connected. This is very useful because the host can log the IP address of clients for future reference (or banning!). -* '''Note: Due to the fact that the previous function name had no suffix, the $ suffix is optional in later QB64 versions!''' - - -''Example:'' A Host logging new chat clients in a Chat program. See the {{KW|_OPENHOST}} example for the rest of the code used. -{{CodeStart}} '' '' -f = {{Cl|FREEFILE}} -{{Cl|OPEN}} "ChatLog.dat" {{Cl|FOR}} {{Cl|APPEND}} {{Cl|AS}} #f ' code at start of host section before DO loop. - - -newclient = {{Cl|_OPENCONNECTION}}(host) ' receive any new client connection handles -{{Cl|IF...THEN|IF}} newclient {{Cl|THEN}} - numclients = numclients + 1 ' increment index - Users(numclients) = newclient ' place handle into array - IP$ = {{Cl|_CONNECTIONADDRESS}}(newclient) - {{Cl|PRINT}} IP$ + " has joined." ' displayed to Host only - {{Cl|PRINT (file statement)|PRINT #f}}, IP$, numclients ' print info to a log file - {{Cl|PRINT (file statement)|PRINT #}}Users(numclients),"Welcome!" ' from Host to new clients only -{{Cl|END IF}} '' '' - -{{CodeEnd}} -: ''Explanation:'' The function returns the new client's IP address to the IP$ variable. Prints the IP and the original login position to a log file. The information can later be used by the host for referance if necessary. The host could set up a ban list too. - - -{{PageSeeAlso}} -* [[_OPENCONNECTION]] -* [[_OPENHOST]] -* [[_OPENCLIENT]] -* [[_CONNECTED]] -* [[IP Configuration]] -* [[WGET]] (HTTP and FTP file transfer) - - -{{PageNavigation}} \ No newline at end of file +#REDIRECT [[_CONNECTIONADDRESS]] \ No newline at end of file diff --git a/internal/help/_CONSOLE.txt b/internal/help/_CONSOLE.txt index 00edbadbd..9be578320 100644 --- a/internal/help/_CONSOLE.txt +++ b/internal/help/_CONSOLE.txt @@ -1,22 +1,23 @@ {{DISPLAYTITLE:_CONSOLE}} -The [[_CONSOLE]] statement can be used to turn OFF a console window or turn it ON after it has been OFF. +The [[_CONSOLE]] statement can be used to turn a console window ON/OFF. {{PageSyntax}} -::: '''_CONSOLE''' {OFF|ON} -::: _DEST '''_CONSOLE''' +: [[_CONSOLE]] {OFF|ON} +: _DEST [[_CONSOLE]] -* _CONSOLE OFF or ON must be used after the [[$CONSOLE]] [[Metacommand]] has established that a console window is desired. -* _CONSOLE OFF turns the console window off once a console has been established using [[$CONSOLE]]:ON or ONLY. -* _CONSOLE ON should only be used AFTER the console window has been turned OFF previously. +* [[_CONSOLE]] OFF or ON must be used after the [[$CONSOLE]] [[Metacommand]] has established that a console window is desired. +* [[_CONSOLE]] OFF turns the console window off once a console has been established using [[$CONSOLE]]:ON or ONLY. +* [[_CONSOLE]] ON should only be used after the console window has been turned OFF previously. * [[_DEST]] [[_CONSOLE]] can be used to send screen output to the console window using QB64 commands such as [[PRINT]]. * [[_SCREENHIDE]] or [[_SCREENSHOW]] can be used to hide or display the main program window. * The [[$SCREENHIDE]] [[Metacommand]] can hide the main program window throughout a program when only the console is used. * '''Note:''' Text can be copied partially or totally from console screens in Windows by highlighting and using the title bar menu. -:: To copy console text output, right click the title bar and select ''Edit'' for ''Mark'' to highlight and repeat to ''Copy'' +:: To copy console text output, right click the title bar and select ''Edit'' for ''Mark'' to highlight and repeat to ''Copy''. +{{PageExamples}} ''Example 1:'' Hiding and displaying a console window. Use [[_DELAY]] to place console in front of main program window. {{CodeStart}} '' '' {{Cl|$CONSOLE}} @@ -35,24 +36,24 @@ The [[_CONSOLE]] statement can be used to turn OFF a console window or turn it O : ''Explanation:'' The [[_DEST|destination]] must be changed with [[_DEST]] [[_CONSOLE]] to get [[INPUT]] from the [[$CONSOLE]] screen. -''Example 2:'' [[SHELL]] "title..." can be used to create a console title, but it must be redone every time it is restored once turned off: +''Example 2:'' [[_CONSOLETITLE]] can be used to create a console title, but it must be redone every time the console window is restored once turned off: {{CodeStart}} '' '' {{Cl|$CONSOLE}} -{{Cl|SHELL}} "title firstone" +{{Cl|_CONSOLETITLE}} "firstone" {{Cl|_DELAY}} 10 {{Cl|_CONSOLE}} OFF {{Cl|_DELAY}} 10 {{Cl|_CONSOLE}} ON -{{Cl|SHELL}} "title secondone" +{{Cl|_CONSOLETITLE}} "secondone" {{CodeEnd}} : ''Note:'' Some versions of Windows may display the program path or Administrator: prefix in console title bars. -''See also:'' -* [[$CONSOLE]] +{{PageSeeAlso}} +* [[$CONSOLE]], [[_CONSOLETITLE]] * [[$SCREENHIDE]], [[$SCREENSHOW]] {{text|(QB64 [[Metacommand]]s)}} * [[_SCREENHIDE]], [[_SCREENSHOW]] * [[_DEST]] diff --git a/internal/help/_CONSOLETITLE.txt b/internal/help/_CONSOLETITLE.txt index 46abddaea..75b1914a8 100644 --- a/internal/help/_CONSOLETITLE.txt +++ b/internal/help/_CONSOLETITLE.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_CONSOLETITLE}} -The '''_CONSOLETITLE''' statement creates the title of the console window using a literal or variable [[STRING|string]]. +The [[_CONSOLETITLE]] statement creates the title of the console window using a literal or variable [[STRING|string]]. {{PageSyntax}} -::: '''_CONSOLETITLE''' ''text$'' +: [[_CONSOLETITLE]] {{Parameter|text$}} +{{PageDescription}} * The ''text$'' used can be a literal or variable [[STRING]] value. +{{PageExamples}} ''Example:'' Hiding the main program window while displaying the console window with a title. {{CodeStart}} '' '' {{Cl|$SCREENHIDE}} @@ -21,6 +23,8 @@ The '''_CONSOLETITLE''' statement creates the title of the console window using {{Cl|END}} {{CodeEnd}} +:''Note:'' You can also use [[SHELL]] "title consoletitle" to set the title of the console window. However, '''the recommended practice is to use [[_CONSOLETITLE]]'''. + ''See also:'' * [[$CONSOLE]], [[_CONSOLE]] diff --git a/internal/help/_CONTROLCHR.txt b/internal/help/_CONTROLCHR.txt index 3e509ebff..c32c7eea9 100644 --- a/internal/help/_CONTROLCHR.txt +++ b/internal/help/_CONTROLCHR.txt @@ -1,24 +1,20 @@ {{DISPLAYTITLE:_CONTROLCHR}} -The '''_CONTROLCHR''' statement can be used to turn OFF control character attributes and allow them to be printed. +The [[_CONTROLCHR]] statement can be used to turn OFF control character attributes and allow them to be printed. {{PageSyntax}} - -::: '''_CONTROLCHR''' {'''OFF'''|ON} +: [[_CONTROLCHR]] {OFF|ON} -{{Parameters}} -* Keyword must be used with '''OFF''' or '''ON'''(default) if previously turned OFF. - - -''Usage:'' -* The [[OFF]] statement allows control characters 0 to 31 to be printed and not format printing as normal text characters. -::For example: '''{{text|PRINT CHR$(7)|green}}''' 'will not [[BEEP]] and '''{{text|PRINT CHR$(9)|green}}''' 'will not tab. +{{PageDescription}} +* The [[OFF]] clause allows control characters 0 to 31 to be printed and not format printing as normal text characters. +::For example: '''{{text|PRINT CHR$(13)|green}}''' 'will not move the cursor to the next line and '''{{text|PRINT CHR$(9)|green}}''' 'will not tab. * The default [[ON]] statement allows [[ASCII#Control_Characters|Control Characters]] to be used as control commands where some will not print or will format prints. -* '''Note:''' File prints may be affected also when using Carriage Return or Line Feed/Form Feed formatting! +* '''Note:''' File prints may be affected also when using Carriage Return or Line Feed/Form Feed formatting. * The QB64 [[IDE]] may allow Alt + number pad character entries, but they must be inside of [[STRING]] values. Otherwise the [[IDE]] may not recognize them. +{{PageExamples}} ''Example:'' Printing the 255 [[ASCII]] characters in [[SCREEN]] 0 with 32 colors. {{CodeStart}} '' '' {{Cl|DIM}} i {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|_BYTE}} @@ -42,7 +38,7 @@ DO {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_CONTROLCHR (function)]] * [[CHR$]], [[ASC]] * [[INKEY$]], [[_KEYHIT]] diff --git a/internal/help/_CONTROLCHR_(function).txt b/internal/help/_CONTROLCHR_(function).txt index f2c92c60b..d1e5680ef 100644 --- a/internal/help/_CONTROLCHR_(function).txt +++ b/internal/help/_CONTROLCHR_(function).txt @@ -1,16 +1,16 @@ {{DISPLAYTITLE:_CONTROLCHR (function)}} -The '''_CONTROLCHR''' function returns the current state of the [[_CONTROLCHR]] statement as 1 when OFF and 0 when ON. - +The [[_CONTROLCHR (function)|_CONTROLCHR]] function returns the current state of the [[_CONTROLCHR]] statement as -1 when OFF and 0 when ON. {{PageSyntax}} -:::status% = _CONTROLCHR +:{{Parameter|status%}} = [[_CONTROLCHR (function)|_CONTROLCHR]] +{{PageDescription}} * The function requires no parameters. * Default return is 0 when the _CONTROLCHR statement has never been used previous to a function read. -* When the statement has been use to turn OFF control characters(1), the characters can be printed as text without screen formatting. +* When the statement has been use to turn OFF control characters, the characters can be printed as text without screen formatting. {{PageSeeAlso}} diff --git a/internal/help/_COPYIMAGE.txt b/internal/help/_COPYIMAGE.txt index 8e22fc949..2ad5a7bea 100644 --- a/internal/help/_COPYIMAGE.txt +++ b/internal/help/_COPYIMAGE.txt @@ -3,28 +3,29 @@ The [[_COPYIMAGE]] function creates an identical designated image in memory with {{PageSyntax}} -: newhandle& = '''_COPYIMAGE'''[(''imageHandle&''[, ''mode%'')]] +: newhandle& = [[_COPYIMAGE]][({{Parameter|imageHandle&]][, {{Parameter|mode%]])]] {{Parameters}} -* The [[LONG]] ''newhandle'' value returned will be different than the source handle value supplied. -* If ''imagehandle'' parameter is omitted or zero is designated, the current software [[_DEST|destination]] screen or image is copied. -* If 1 is designated instead of an ''imagehandle'', it designates the last GL hardware surface to copy. +* The [[LONG]] ''newhandle&'' value returned will be different than the source handle value supplied. +* If ''imageHandle&'' parameter is omitted or zero is designated, the current software [[_DEST|destination]] screen or image is copied. +* If 1 is designated instead of an ''imageHandle&'', it designates the last OpenGL hardware surface to copy. * ''Mode'' 32 can be used to convert 256 color images to 32 bit colors. -* ''Mode'' 33 images are hardware accelerated in GL, and are created using [[_LOADIMAGE]] or [[_COPYIMAGE]]. ([[_NEWIMAGE]] later) +* ''Mode'' 33 images are hardware accelerated in '''version 1.000 and up''', and are created using [[_LOADIMAGE]] or [[_COPYIMAGE]]. -''Usage:'' +{{PageDescription}} * The function copies any image or screen handle to a new and unique negative [[LONG]] handle value. * Valid copy handles are less than -1. Invalid handles return -1 or 0 if it was never created. * Every attribute of the passed image or program screen is copied to a new handle value in memory. -* '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' -: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opague. +* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' -* '''It is IMPORTANT to free discarded images with [[_FREEIMAGE]] to prevent PC memory allocation errors!''' -* '''Do NOT try to free image handles currently being used as the active [[SCREEN]]! Change screen modes first.''' +* '''It is important to free discarded images with [[_FREEIMAGE]] to prevent PC memory allocation errors!''' +* '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.''' +{{PageExamples}} ''Example:'' Restoring a Legacy SCREEN using the _COPYIMAGE return value. {{CodeStart}}'' '' @@ -47,7 +48,7 @@ DO: {{Cl|SLEEP}}: {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" : ''Note:'' Only free valid handle values with [[_FREEIMAGE]] AFTER a new [[SCREEN]] mode is being used by the program. -''Example 2:'' '''QB64 GL''' program copies desktop to a hardware image to form a 3D triangle: +''Example 2:'' Program that copies desktop to a hardware image to form a 3D triangle ('''version 1.000 and up'''): {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) my_hardware_handle = {{Cl|_COPYIMAGE}}({{Cl|_SCREENIMAGE}}, 33) 'take a screenshot and use it as our texture diff --git a/internal/help/_COPYPALETTE.txt b/internal/help/_COPYPALETTE.txt index 9dbc8164f..c4e436d15 100644 --- a/internal/help/_COPYPALETTE.txt +++ b/internal/help/_COPYPALETTE.txt @@ -7,8 +7,8 @@ The [[_COPYPALETTE]] statement copies the color palette intensities from one 4 o {{PageDescription}} -* Palette Intensity settings are '''NOT''' used by 24/32 bit images! '''Only use with 4 or 8 BPP images!''' -* [[_PIXELSIZE]] function returns of 1 indicate that _COPYPALETTE can be used. 4 indicates 24/32 bit! +* Palette Intensity settings are '''not''' used by 24/32 bit images. Use only with 4 or 8 BPP images. +* [[_PIXELSIZE]] function returns 1 to indicate that _COPYPALETTE can be used. 4 indicates 24/32 bit images. * If {{Parameter|sourceImageHandle&}} is omitted, it is assumed to be the current read page. * If {{Parameter|destinationImageHandle&}} is omitted, it is assumed to be the current write page. * If either of the images specified by {{Parameter|sourceImageHandle&}} or {{Parameter|destinationImageHandle&}} do not use a palette, an [[ERROR Codes|illegal function call]] error is returned. @@ -16,14 +16,15 @@ The [[_COPYPALETTE]] statement copies the color palette intensities from one 4 o * When loading 4 or 8 BPP image files, it is necessary to adopt the color palette of the image or it may not have the correct colors! -''See Example:'' [[SAVEIMAGE]] +{{PageExamples}} +* See the example in [[SAVEIMAGE]]. {{PageSeeAlso}} -* {{KW|_LOADIMAGE}} -* {{KW|_PIXELSIZE}} -* {{KW|_PALETTECOLOR}}, {{KW|_PALETTECOLOR (function)}} -* {{KW|PALETTE}}, [[Images]] +* [[_LOADIMAGE]] +* [[_PIXELSIZE]] +* [[_PALETTECOLOR]], [[_PALETTECOLOR (function)]] +* [[PALETTE]], [[Images]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_CV.txt b/internal/help/_CV.txt index 9bdbb5ee4..fd8424d11 100644 --- a/internal/help/_CV.txt +++ b/internal/help/_CV.txt @@ -1,18 +1,23 @@ {{DISPLAYTITLE:_CV}} -The [[_CV]] function is used to convert [[_MK$]], [[ASCII]], {{KW|STRING}} values to numerical values. +The [[_CV]] function is used to convert [[_MK$]], [[ASCII]], [[STRING]] values to numerical values. {{PageSyntax}} -:''result'' = {{KW|_CV}}({{Parameter|numericalType}}, {{Parameter|stringValue$}}) +:{{Parameter|result}} = [[_CV]]({{Parameter|numericalType}}, {{Parameter|MKstringValue$}}) + + +{{Parameters}} +* {{Parameter|numericalType}} is any number type: [[INTEGER]], [[LONG]], [[SINGLE]], [[DOUBLE]], [[_INTEGER64]], [[_FLOAT]], [[_BYTE]] or [[_BIT]]. +* Integer, Long, Byte and Bit values can be signed or [[_UNSIGNED]]. +* The {{Parameter|MKstringvalue$}} parameter must be a string value generated by [[_MK$]] {{PageDescription}} -* {{Parameter|numericalType}} is any number type: {{KW|INTEGER}}, {{KW|LONG}}, {{KW|SINGLE}}, {{KW|DOUBLE}}, {{KW|_INTEGER64}}, {{KW|_BYTE}} or {{KW|_BIT}}. -* Integer, Long, Byte and Bit values can be Signed or {{KW|_UNSIGNED}}. -* The string number value type must match the numerical type parameter used. +* The {{Parameter|MKstringvalue$}} value type must match the numerical type parameter used. * [[_MK$]] [[STRING|string]] values consist of [[ASCII]] characters in the same byte length as the number value type. +{{PageExamples}} ''Example:'' Using the _MK$ and _CV functions: {{CodeStart}} '' '' {{Cl|DIM}} i64 {{Cl|AS}} {{Cl|_INTEGER64}} @@ -32,17 +37,19 @@ I64: 2305843009213693952 _MK$: _CV: 2305843009213693952 {{OutputEnd}} -:The _MK$ string result may not print anything to the screen as this example proved. +:The _MK$ string result may not print anything to the screen, as in the example above, unless [[_CONTROLCHR]] is set to OFF. {{PageSeeAlso}} +* [[_MK$]] {{text|(QB64 string conversion function)}} * [[MKI$]], [[CVI]], [[INTEGER]] * [[MKL$]], [[CVL]], [[LONG]] * [[MKS$]], [[CVS]], [[SINGLE]] * [[MKD$]], [[CVD]], [[DOUBLE]] * [[MKSMBF$]], [[CVSMBF]] {{text|(Microsoft Binary Format)}} * [[MKDMBF$]], [[CVDMBF]] {{text|(Microsoft Binary Format)}} -* [[PDS(7.1) Procedures#CURRENCY|CURRENCY]] +* [[PDS (7.1) Procedures#CURRENCY|CURRENCY]] +* [[_CONTROLCHR]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_CWD$.txt b/internal/help/_CWD$.txt index c6cf6f36e..9f2ba2a74 100644 --- a/internal/help/_CWD$.txt +++ b/internal/help/_CWD$.txt @@ -1,10 +1,10 @@ {{DISPLAYTITLE:_CWD$}} -The [[_CWD$]] function returns the current working directory path as a string value with the path separator of the [[_OS$|OS]] used (\ on Windows, / on Linux/Mac). +The [[_CWD$]] function returns the current working directory path as a string value without a trailing path separator. {{PageSyntax}} -::: workingdirectory$ = '''_CWD$''' +: {{Parameter|workingDirectory$}} = [[_CWD$]] {{PageDescription}} @@ -12,14 +12,14 @@ The [[_CWD$]] function returns the current working directory path as a string va * The current working directory can be changed with the [[CHDIR]] or [[SHELL]] command; CHDIR sets it, _CWD$ returns it. * Path returns will change only when the working path has changed. When in C:\ and run QB64\cwd.exe, it will still return C:\ * The current working directory string can be used in [[OPEN]] statements and [[SHELL]] commands that deal with files. -* Works in Windows, MAC OSX and Linux. [[_OS$]] can be used by a program to predict the proper slash separations in different OS's. +* Works in Windows, macOS and Linux. [[_OS$]] can be used by a program to predict the proper slash separations in different OS's. {{PageErrors}} * If an error occurs while obtaining the working directory from the operating system, [[ERROR Codes|error code]] 51 (Internal Error) will be generated. - +{{PageExamples}} ''Example:'' Get the current working directory, and move around the file system: {{CodeStart}} '' '' startdir$ = _CWD$ @@ -38,7 +38,7 @@ And now we're back in C:\QB64 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[CHDIR]] {{text|(Change the current working directory)}} * [[RMDIR]] {{text|(Remove a directory in the file system)}} * [[KILL]] {{text|(Delete a file in the file system)}} diff --git a/internal/help/_D2G.txt b/internal/help/_D2G.txt index c6ea44c49..e91ed45a9 100644 --- a/internal/help/_D2G.txt +++ b/internal/help/_D2G.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_D2G}} -The '''_D2G''' function converts a DEGREE value into a GRADIENT value. +The [[_D2G]] function converts a '''degree''' value into a '''gradient''' value. {{PageSyntax}} -:: result = [[_D2G]](''num'') +: {{Parameter|result}} = [[_D2G]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Degrees into Gradient. {{CodeStart}} INPUT "Give me an angle in Degrees ", D @@ -21,7 +23,7 @@ That angle in Gradient is 66.66666 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2R]] * [[_G2D]], [[_G2R]] * [[_R2D]], [[_R2G]] diff --git a/internal/help/_D2R.txt b/internal/help/_D2R.txt index beb23e1cd..167d199d5 100644 --- a/internal/help/_D2R.txt +++ b/internal/help/_D2R.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_D2R}} -The '''_D2R''' function converts a DEGREE value into a RADIAN value. +The [[_D2R]] function converts a '''degree''' value into a '''radian''' value. {{PageSyntax}} -:: result = [[_D2R]](''num'') +:: {{Parameter|result}} = [[_D2R]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Degrees into Radians. {{CodeStart}} INPUT "Give me an angle in Degrees ", D @@ -21,7 +23,7 @@ That angle in Radians is 1.047198 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]], [[_D2R]] * [[_G2D]], [[_G2R]] * [[_R2D]], [[_R2G]] diff --git a/internal/help/_DEFAULTCOLOR.txt b/internal/help/_DEFAULTCOLOR.txt index c4c7bc1e4..14af082c8 100644 --- a/internal/help/_DEFAULTCOLOR.txt +++ b/internal/help/_DEFAULTCOLOR.txt @@ -3,15 +3,16 @@ The [[_DEFAULTCOLOR]] function returns the current default text color for an ima {{PageSyntax}} -:''result&'' = {{KW|_DEFAULTCOLOR}} [({{Parameter|imageHandle&}})] +:{{Parameter|result&}} = [[_DEFAULTCOLOR]] [({{Parameter|imageHandle&}})] {{PageDescription}} * If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page or image designated by [[_DEST]]. -* If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error occurs. Check handle values first! -* Default foreground colors: [[SCREEN]] 0 = 7, [[SCREEN]] 1 and 10 = 3, [[SCREEN]] 2 and 11 = 1. All other [[SCREEN]]s = 15. +* If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error occurs. Check handle values first. +* Default foreground colors are: [[SCREEN]] 0 = 7, [[SCREEN]] 1 and 10 = 3, [[SCREEN]] 2 and 11 = 1. All other [[SCREEN]]s = 15. +{{PageExamples}} ''Example:'' The default color is the color assigned to the text foreground. The [[SCREEN]] 12 default is [[COLOR]] 15. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 diff --git a/internal/help/_DEFINE.txt b/internal/help/_DEFINE.txt index 36555c940..147ddcb88 100644 --- a/internal/help/_DEFINE.txt +++ b/internal/help/_DEFINE.txt @@ -1,25 +1,26 @@ {{DISPLAYTITLE:_DEFINE}} -'''_DEFINE''' defines a set of variable names according to their first character as a specified datatype. +[[_DEFINE]] defines a set of variable names according to their first character as a specified data type. {{PageSyntax}} -:[[_DEFINE]] ''letter''[''-range'', ...] [[AS]] [{{KW|_UNSIGNED}}] data[[type]] +:[[_DEFINE]] {{Parameter|letter}}[{{Parameter|-range}}, ...] [[AS]] [{{KW|_UNSIGNED}}] data[[type]] {{Parameters}} * Variable start ''letter range'' is in the form firstletter-endingletter (like A-C) or just a single letter. -* ''Datatypes'': [[INTEGER]], [[SINGLE]], [[DOUBLE]], [[LONG]], [[STRING]], [[_BIT]], [[_BYTE]], [[_INTEGER64]], [[_FLOAT]], [[_OFFSET]], [[_MEM]] -* Can also use the [[_UNSIGNED]] definition for positive whole [[INTEGER]] type numerical values only. +* ''Data types'': [[INTEGER]], [[SINGLE]], [[DOUBLE]], [[LONG]], [[STRING]], [[_BIT]], [[_BYTE]], [[_INTEGER64]], [[_FLOAT]], [[_OFFSET]], [[_MEM]] +* Can also use the [[_UNSIGNED]] definition for positive whole [[INTEGER]] type numerical values. -''Usage:'' -* '''When a variable has not been defined or has no type suffix, the value defaults to a [[SINGLE]] floating point value.''' -* _DEFINE sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program(even in conditional statement blocks not executed and subsequent [[SUB]] procedures). -* '''NOTE: Many Qbasic keyword variable names CAN be used with a [[STRING]] suffix($) ONLY! You CANNOT use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements!''' -* '''Qbasic's IDE''' may add DEF statements before any [[SUB]] or [[FUNCTION]]. QB64(like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures! If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. May also affect [[$INCLUDE]] procedures! - +{{PageDescription}} +* '''When a variable has not been defined or has no type suffix, the value defaults to a [[SINGLE]] precision floating point value.''' +* _DEFINE sets the [[type]] of all variable names with the starting letter(s) or letter ranges when encountered in the progression of the program (even in conditional statement blocks not executed and subsequent [[SUB]] procedures). +* '''NOTE: Many Qbasic keyword variable names CAN be used with a [[STRING]] suffix ($)! You cannot use them without the suffix, use a numerical suffix or use [[DIM]], [[REDIM]], [[_DEFINE]], [[BYVAL]] or [[TYPE]] variable [[AS]] statements.''' +* '''Qbasic's IDE''' added DEF statements before any [[SUB]] or [[FUNCTION]]. '''QB64''' (like QB) will change all variable types in subsequent sub-procedures to that default variable type without giving a [[ERROR Codes|"Parameter Type Mismatch"]] warning or adding the proper DEF statement to subsequent procedures. If you do not want that to occur, either remove that DEF statement or add the proper DEF type statements to subsequent procedures. +* May also affect [[$INCLUDE]] procedures. +{{PageExamples}} ''Example:'' Defining variables that start with the letters A, B, C or F as unsigned integers, including the ''Add2'' [[FUNCTION]]. {{CodeStart}} '' '' {{Cl|_DEFINE}} A-C, F {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|INTEGER}} diff --git a/internal/help/_DELAY.txt b/internal/help/_DELAY.txt index c537299ac..324eb24c2 100644 --- a/internal/help/_DELAY.txt +++ b/internal/help/_DELAY.txt @@ -1,13 +1,13 @@ {{DISPLAYTITLE:_DELAY}} -The [[_DELAY]] statement suspends program execution for a {{KW|SINGLE}} value of seconds. +The [[_DELAY]] statement suspends program execution for a [[SINGLE]] value of seconds. {{PageSyntax}} -:{{KW|_DELAY}} {{Parameter|seconds!}} +:[[_DELAY]] {{Parameter|seconds!}} {{PageDescription}} -* {{Parameter|seconds!}} is the time to wait, accurate to nearest millisecond(.001). +* {{Parameter|seconds!}} is the time to wait, accurate to nearest millisecond (.001). * While waiting, cpu cycles are relinquished to other applications. * Delays are not affected by midnight timer corrections. diff --git a/internal/help/_DEPTHBUFFER.txt b/internal/help/_DEPTHBUFFER.txt index 24a389da4..277cfb81c 100644 --- a/internal/help/_DEPTHBUFFER.txt +++ b/internal/help/_DEPTHBUFFER.txt @@ -1,29 +1,24 @@ {{DISPLAYTITLE:_DEPTHBUFFER}} -The '''_DEPTHBUFFER''' statement turns depth buffering ON or OFF, LOCKs or _CLEARS the buffer. +The [[_DEPTHBUFFER]] statement turns depth buffering ON or OFF, LOCKs or _CLEARS the buffer. {{PageSyntax}} -::: '''_DEPTHBUFFER''' {ON|OFF|LOCK|_CLEAR}[,handle] +: [[_DEPTHBUFFER]] {ON|OFF|LOCK|_CLEAR}[,handle&] {{PageDescription}} * Depth buffers store the distance of each pixel on an image/surface. When 3D drawing occurs new pixels are only drawn if they are closer than the existing pixels. After all content is drawn, it results in a scene which looks correct because content which is closer hides content which is further away. * Depth buffers are automatically created for any hardware image or surface which is the target/destination of a 3D command (such as the 3D version of [[_MAPTRIANGLE]]). * The buffering can be turned ON, OFF or LOCKed. The default state is ON. -* _DEPTHBUFFER _CLEAR can be used to reset/erase the depth buffer, meaning that future drawing will not be blocked by existing/previously buffered depth content. +* [[_DEPTHBUFFER]] _CLEAR can be used to reset/erase the depth buffer, meaning that future drawing will not be blocked by existing/previously buffered depth content. * Whenever _DISPLAY is called the primary surface's depth buffer is automatically _CLEARed, so unless you are drawing onto a hardware image you may never need to use this option. * LOCKing the depth buffer makes it read only. New content cannot be drawn unless it is closer than existing content, but when that new content is drawn it will not update the depth buffer. * Turning OFF or LOCKing the depth buffer is typically performed when semi-transparent content is being drawn. -''Photo:'' -Here's another screenshot which shows rending to 2d images then rendering to the screen. The difference is that QB64 is adding a hardware depth-buffer to the destination images on demand when and if it requires one. Note which image is not using a depth-buffer. In QB64 a depth-buffer is implied unless you specifically state not to use one. - -[http://i301.photobucket.com/albums/nn53/burger2227/YUNEEEDaDEPTHBUFFER.png You need a _DEPTHBUFFER] - -''See also:'' +{{PageSeeAlso}} * [[_MAPTRIANGLE]] * [[_PUTIMAGE]] * [[_DISPLAY]] diff --git a/internal/help/_DESKTOPHEIGHT.txt b/internal/help/_DESKTOPHEIGHT.txt index 1d4e9ce41..6d5419fd4 100644 --- a/internal/help/_DESKTOPHEIGHT.txt +++ b/internal/help/_DESKTOPHEIGHT.txt @@ -1,18 +1,21 @@ {{DISPLAYTITLE:_DESKTOPHEIGHT}} -The '''_DESKTOPHEIGHT''' function returns the height of the users current desktop. +The [[_DESKTOPHEIGHT]] function returns the height of the users current desktop. {{PageSyntax}} -::: y& = '''_DESKTOPHEIGHT''' +: {{Parameter|y&}} = [[_DESKTOPHEIGHT]] {{PageDescription}} * No parameters are needed for this function. * This returns the height of the user's desktop, not the size of any screen or window which might be open on that desktop. -* Only available for use in GL. SDL version does not support this keyword. +==Availability== +* '''Version 1.000 and up.''' + +{{PageExamples}} {{CodeStart}} s& = {{Cl|_NEWIMAGE}}(800, 600, 256) @@ -22,9 +25,7 @@ The '''_DESKTOPHEIGHT''' function returns the height of the users current deskto {{CodeEnd}} -: ''Explanation:'' This will print the size of the user desktop (in my case currently 1920, 1080), and then the size of the current screen (800,600). - - +: ''Explanation:'' This will print the size of the user desktop (for example ''1920, 1080'' for a standard hdmi monitor), and then the size of the current [[SCREEN|screen]] (800, 600). {{PageSeeAlso}} diff --git a/internal/help/_DESKTOPWIDTH.txt b/internal/help/_DESKTOPWIDTH.txt index 246eff650..c25728bb4 100644 --- a/internal/help/_DESKTOPWIDTH.txt +++ b/internal/help/_DESKTOPWIDTH.txt @@ -1,18 +1,21 @@ {{DISPLAYTITLE:_DESKTOPWIDTH}} -The '''_DESKTOPWIDTH''' function returns the width of the users current desktop. +The [[_DESKTOPWIDTH]] function returns the width of the users current desktop. {{PageSyntax}} -::: x& = '''_DESKTOPWIDTH''' +: {{Parameter|x&}} = [[_DESKTOPWIDTH]] {{PageDescription}} * No parameters are needed for this function. * This returns the width of the user's desktop, not the size of any screen or window which might be open on that desktop. -* Only available for use in GL. SDL version does not support this keyword. +==Availability== +* '''Version 1.000 and up.''' + +{{PageExamples}} {{CodeStart}} s& = {{Cl|_NEWIMAGE}}(800, 600, 256) @@ -22,9 +25,7 @@ The '''_DESKTOPWIDTH''' function returns the width of the users current desktop. {{CodeEnd}} -: ''Explanation:'' This will print the size of the user desktop (in my case currently 1920, 1080), and then the size of the current screen (800,600). - - +: ''Explanation:'' This will print the size of the user desktop (for example ''1920, 1080'' for a standard hdmi monitor), and then the size of the current [[SCREEN|screen]] (800, 600). {{PageSeeAlso}} diff --git a/internal/help/_DEST.txt b/internal/help/_DEST.txt index 2bd8886d2..fe4d4dbfd 100644 --- a/internal/help/_DEST.txt +++ b/internal/help/_DEST.txt @@ -9,11 +9,12 @@ The [[_DEST]] statement sets the current write image or page. All graphic and pr {{PageDescription}} * {{Parameter|imageHandle&}} is the handle of the image that will act as the current write page. * '''_DEST 0''' refers to the present program [[SCREEN]]. You can use 0 to refer to the present program [[SCREEN]]. -* _DEST [[_CONSOLE]] can set the destination to send information to a console window using [[PRINT]] or [[INPUT]]. -* If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error occurs. Always check for bad handle values of -1 first! +* [[_DEST]] [[_CONSOLE]] can set the destination to send information to a console window using [[PRINT]] or [[INPUT]]. +* If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error occurs. Always check for valid handle values first ({{Parameter|imageHandle&}} < -1). *''Note:'' Use [[_SOURCE]] when you need to read a page or image with [[POINT]], [[GET (graphics statement)|GET]] or the [[SCREEN (function)|SCREEN]] function. +{{PageExamples}} ''Example 1:'' Placing a center point and a circle using [[_CLEARCOLOR]] to eliminate the background color black. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 13 'program screen can use 256 colors diff --git a/internal/help/_DEST_(function).txt b/internal/help/_DEST_(function).txt index 0f9ae6411..951fe2386 100644 --- a/internal/help/_DEST_(function).txt +++ b/internal/help/_DEST_(function).txt @@ -1,16 +1,16 @@ {{DISPLAYTITLE:_DEST (function)}} -The '''_DEST''' function returns the handle value of the current write page (the image used for drawing). +The [[_DEST]] function returns the handle value of the current write page (the image used for drawing). {{PageSyntax}} -:''result&'' = '''_DEST'' +:{{Parameter|result&}} = [[_DEST]] {{PageDescription}} * The current write page is where all drawing occurs by default. * The value returned is the same as the latest [[SCREEN]]'s handle when creating custom screen modes using [[_NEWIMAGE]]. -* Keep the _NEWIMAGE handle values when you move to another SCREEN mode so that you can return to that screen later. You can go to another screen mode and return without having to redo the screen! -* _DEST return values do not change in legacy screen modes. The value will not help restore them. +* Keep the _NEWIMAGE handle values when you move to another SCREEN mode so that you can return to that screen later. You can go to another screen mode and return without having to redo the screen. +* [[_DEST]] return values do not change in legacy screen modes. The value will not help restore them. {{PageSeeAlso}} diff --git a/internal/help/_DEVICE$.txt b/internal/help/_DEVICE$.txt index 0ff4ffc6f..781cba631 100644 --- a/internal/help/_DEVICE$.txt +++ b/internal/help/_DEVICE$.txt @@ -3,11 +3,11 @@ The '''_DEVICE$''' function returns a [[STRING]] value holding the controller ty {{PageSyntax}} -::: device$ = _DEVICE$(''device_number'') +: {{Parameter|device$}} = _DEVICE$({{Parameter|device_number}}) -* '''[[_DEVICES]] function MUST be read first to get the number of devices and to enable [[_DEVICE$]] and [[_DEVICEINPUT]].''' -* The ''device_number'' parameter indicates the number of the controller device to be read. +* The '''[[_DEVICES]] function must be read first to get the number of devices and to enable [[_DEVICE$]] and [[_DEVICEINPUT]].''' +* The {{Parameter|device_number}} parameter indicates the number of the controller device to be read. * Returns the [[STRING]] control type, name of the device and input types each can use included in brackets: ::* Control type: ::: [KEYBOARD] always listed as first device when keyboard(s) available. Only one keyboard will show. @@ -19,10 +19,11 @@ The '''_DEVICE$''' function returns a [[STRING]] value holding the controller ty ::: [{{KW|AXIS}}] indicates there are stick types of input. [[_LASTAXIS]] can return the number of axis available. ::: [{{KW|WHEEL}}] indicates that a scrolling input can be read. [[_LASTWHEEL]] can return the number of wheels available. -* '''Device numbers above the number of [[_DEVICES|devices]] found will return an OS error!''' +* '''Device numbers above the number of [[_DEVICES|devices]] found will return an OS error.''' * Devices found include keyboard, mouse, joysticks, game pads and multiple stick game controllers. +{{PageExamples}} ''Example 1:'' Checking for the system's input devices and the number of buttons available. {{CodeStart}} '' '' devices = {{Cl|_DEVICES}} 'MUST be read in order for other 2 device functions to work! @@ -53,7 +54,7 @@ Buttons: 9 Axis: 6 Wheels: 0 {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_DEVICES]], [[_DEVICEINPUT]] * [[_LASTBUTTON]], [[_LASTAXIS]], [[_LASTWHEEL]] * [[_BUTTON]], [[_BUTTONCHANGE]] diff --git a/internal/help/_DEVICEINPUT.txt b/internal/help/_DEVICEINPUT.txt index 627cca9bc..545367d9f 100644 --- a/internal/help/_DEVICEINPUT.txt +++ b/internal/help/_DEVICEINPUT.txt @@ -3,26 +3,26 @@ The '''_DEVICEINPUT''' function returns the device number when a controller devi {{PageSyntax}} -::: device% = '''_DEVICEINPUT''' -::: device_active% = '''_DEVICEINPUT('''''device_number%''''')''' +: {{Parameter|device%}} = [[_DEVICEINPUT]] +: {{Parameter|device_active%}} = [[_DEVICEINPUT]]({{Parameter|device_number%}}) {{Parameters}} -* Use the _DEVICEINPUT ''device'' [[INTEGER]] returned to find the number of the controller device being used. -* A literal specific ''device_number'' parameter can be used to return -1 if active or 0 if inactive. {{text|EX: '''WHILE _DEVICEINPUT(2)'''|green}} +* Use the _DEVICEINPUT {{Parameter|device%}} [[INTEGER]] returned to find the number of the controller device being used. +* A literal specific {{Parameter|device_number%}} parameter can be used to return -1 if active or 0 if inactive. {{text|EX: '''WHILE _DEVICEINPUT(2)'''|green}} -''Description:'' -* Use [[_DEVICES]] to find the number of controller devices available BEFORE using this function! - +{{PageDescription}} +* Use [[_DEVICES]] to find the number of controller devices available BEFORE using this function. * [[_DEVICE$]] can be used to list the device names and control types using valid [[_DEVICES]] numbers. * When a device button is pressed or a scroll wheel or axis is moved, the device number will be returned. -* Devices are numbered as 1 for keyboard and 2 for mouse. Other controller devices will be numbered 3 or more if installed. +* Devices are numbered as 1 for keyboard and 2 for mouse. Other controller devices will be numbered 3 or higher if installed. * [[_LASTBUTTON]], [[_LASTAXIS]], or [[_LASTWHEEL]] will indicate the number of functions available with the specified ''device'' number. * User input events can be monitored reading valid numbered [[_AXIS]], [[_BUTTON]], [[_BUTTONCHANGE]] or [[_WHEEL]] functions. * ''Note:'' [[ON...GOSUB|ON _DEVICEINPUT GOSUB]] keyboard, mouse, gamecontrol can be used to control the devices 1,2 and 3, etc. +{{PageExamples}} ''Example 1:'' Checking device controller interfaces and finding out what devices are being used. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|_DEVICES}} @@ -96,7 +96,7 @@ controller: : ''Note:'' [[ON...GOSUB]] and [[ON...GOTO]] events require numerical values to match the order of line labels listed in the event used inside loops. -''See also:'' +{{PageSeeAlso}} * [[_DEVICES]], [[_DEVICE$]] * [[_LASTBUTTON]], [[_LASTAXIS]], [[_LASTWHEEL]] * [[_BUTTON]], [[_AXIS]], [[_WHEEL]] diff --git a/internal/help/_DEVICES.txt b/internal/help/_DEVICES.txt index f85f9d755..2b748d0a4 100644 --- a/internal/help/_DEVICES.txt +++ b/internal/help/_DEVICES.txt @@ -1,16 +1,18 @@ {{DISPLAYTITLE:_DEVICES}} -The '''_DEVICES''' function returns the number of INPUT devices on your computer including keyboard, mouse and game devices. +The [[_DEVICES]] function returns the number of INPUT devices on your computer including keyboard, mouse and game devices. {{PageSyntax}} -::: device_count% = _DEVICES +: {{Parameter|device_count%}} = [[_DEVICES]] +{{PageDescription}} * Returns the number of devices that can be listed separately with the [[_DEVICE$]] function by the device number. * Devices include keyboard, mouse, joysticks, game pads and multiple stick game controllers. -* '''Note: This function MUST be read before trying to use the [[_DEVICE$]], [[_DEVICEINPUT]] or _LAST control functions!''' +* '''Note: This function must be read before trying to use the [[_DEVICE$]], [[_DEVICEINPUT]] or _LAST control functions.''' +{{PageExamples}} ''Example:'' Checking for the system's input devices. {{CodeStart}} '' '' devices = {{Cl|_DEVICES}} 'MUST be read in order for other 2 device functions to work! @@ -29,11 +31,12 @@ Buttons: 3 :Note: The [[STRIG]]/[[STICK]] commands won't read from the keyboard or mouse device the above example lists. -''See also:'' +{{PageSeeAlso}} * [[_DEVICE$]], [[_DEVICEINPUT]] * [[_LASTBUTTON]], [[_LASTAXIS]], [[_LASTWHEEL]] * [[_BUTTON]], [[_BUTTONCHANGE]] * [[_AXIS]], [[_WHEEL]] +* [[_MOUSEINPUT]], [[_MOUSEX]], [[_MOUSEBUTTON]] * [[STRIG]], [[STICK]] * [[ON STRIG(n)]], [[STRIG(n)]] * [[Controller Devices]] diff --git a/internal/help/_DIREXISTS.txt b/internal/help/_DIREXISTS.txt index 56b06f519..f8ead5769 100644 --- a/internal/help/_DIREXISTS.txt +++ b/internal/help/_DIREXISTS.txt @@ -1,21 +1,30 @@ {{DISPLAYTITLE:_DIREXISTS}} -The '''_DIREXISTS''' function determines if a designated file path or folder exists and returns True or False. +The [[_DIREXISTS]] function determines if a designated file path or folder exists and returns true (-1) or false (0). {{PageSyntax}} - -::: IF _DIREXISTS(''filepath$'') THEN +: {{Parameter|dirExists%}} = [[_DIREXISTS]]({{Parameter|filepath$}}) -* The ''filepath'' parameter can be a literal or variable [[STRING|string]] path value. +{{PageDescription}} +* The {{Parameter|filepath$}} parameter can be a literal or variable [[STRING|string]] path value. * The function returns -1 when a path or folder exists and 0 when it does not. * The function reads the system information directly without using a [[SHELL]] procedure. * The function will use the appropriate Operating System path separators. [[_OS$]] can determine the operating system. * '''This function does not guarantee that a path can be accessed, only that it exists.''' -* '''NOTE: CD drives may request a disk when empty!''' To find drives in Windows, use this API Library: [http://www.qb64.net/wiki/index.php/Windows_Libraries#Disk_Drives Disk Drives] +* '''NOTE: Checking if a folder exists in a CD drive may cause the tray to open automatically to request a disk when empty.''' To find drives in Windows, use this API Library: [http://www.qb64.net/wiki/index.php/Windows_Libraries#Disk_Drives Disk Drives] -''See also:'' +{{PageExamples}} +{{Parameter|Example:'' Checks if a folder exists before proceeding. +{{CodeStart}} +{{Cl|IF}} {{Cl|_DIREXISTS}}("internal\temp") THEN + {{Cl|PRINT}} "Folder found." +{{Cl|END IF}} +{{CodeEnd}}}} + + +{{PageSeeAlso}} * [[_FILEEXISTS]] * [[SHELL]] * [[_OS$]] diff --git a/internal/help/_DISPLAY.txt b/internal/help/_DISPLAY.txt index 20a2fb801..09f288cd9 100644 --- a/internal/help/_DISPLAY.txt +++ b/internal/help/_DISPLAY.txt @@ -3,17 +3,19 @@ The [[_DISPLAY]] statement turns off the automatic display while only displaying {{PageSyntax}} -::: '''_DISPLAY''' +: [[_DISPLAY]] -''Usage:'' -* '''_DISPLAY''' turns off the auto refresh screen default [[_AUTODISPLAY]] when used. Prevents screen flickering. +{{PageDescription}} +* '''_DISPLAY''' turns off the auto refresh screen default [[_AUTODISPLAY]] behavior. Prevents screen flickering. * Call _DISPLAY each time the screen graphics are to be displayed. Place call after the image has been changed. -* Re-enable automatic display refreshing by calling [[_AUTODISPLAY]]. If it isn't re-enabled, things may not be displayed later! -* _DISPLAY tells '''QB64GL''' to render all of the hardware [[_PUTIMAGE]] commands loaded into the buffer previously. -* '''QB64GL''' can set the graphic rendering order of _SOFTWARE, _HARDWARE, and _GLRENDER with [[_DISPLAYORDER]]. +* Re-enable automatic display refreshing by calling [[_AUTODISPLAY]]. If it isn't re-enabled, things may not be displayed later. +* _DISPLAY tells '''QB64''' to render all of the hardware [[_PUTIMAGE]] commands loaded into the buffer previously. +* The [[_AUTODISPLAY (function)]] can be used to detect the current display behavior. +* '''QB64''' can set the graphic rendering order of _SOFTWARE, _HARDWARE, and _GLRENDER with [[_DISPLAYORDER]]. +{{PageExamples}} ''Example 1:'' Displaying a circle bouncing around the screen. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 12 @@ -34,7 +36,7 @@ dx = 3: dy = 3 'number of pixel moves per loop :''Explanation:'' The loop is set with [[_LIMIT]] to 100 frames per second to limit CPU usage and the speed of the ball. Each loop a circle is drawn while the previous one is erased when the coordinates change. _DISPLAY only shows the new circle position once each loop. The '''_DISPLAY''' routine eliminates the need for setting [[SCREEN (statement)|SCREEN]] swap pages, [[CLS]] and [[PCOPY]]. _DISPLAY keeps the image off of the screen until the changes have all completed. Drawing 40 circles every loop helps slow down the ball. -''Example 2:'' In ''QB64GL''' [[_DISPLAY]] must be used to render hardware images placed with [[_PUTIMAGE]]. +''Example 2:'' [[_DISPLAY]] must be used to render hardware images placed with [[_PUTIMAGE]] ('''version 1.000 and up'''). {{CodeStart}} '' '' {{Cl|CONST}} MenuHeight = 200 @@ -71,8 +73,8 @@ DO {{PageSeeAlso}} * [[_DISPLAY (function)]] -* [[_DISPLAYORDER]] {{text|(QB64GL only)}} -* [[_AUTODISPLAY]] {{text|(default display mode)}} +* [[_DISPLAYORDER]] +* [[_AUTODISPLAY]], [[_AUTODISPLAY (function)]] * [[_PUTIMAGE]] * [[PCOPY]] diff --git a/internal/help/_DISPLAYORDER.txt b/internal/help/_DISPLAYORDER.txt index d6594a97f..aad5b1933 100644 --- a/internal/help/_DISPLAYORDER.txt +++ b/internal/help/_DISPLAYORDER.txt @@ -1,21 +1,21 @@ {{DISPLAYTITLE:_DISPLAYORDER}} -The '''_DISPLAYORDER''' statement defines the order to render software, hardware and custom-OpenGL-code in '''QB64GL''' only. +The [[_DISPLAYORDER]] statement defines the order to render software, hardware and custom-OpenGL-code. {{PageSyntax}} -:: '''_DISPLAYORDER''' [{_SOFTWARE|_HARDWARE|_HARDWARE1|_GLRENDER}][, ...][, ...][, ...][, ...] +: [[_DISPLAYORDER]] [{_SOFTWARE|_HARDWARE|_HARDWARE1|_GLRENDER}][, ...][, ...][, ...][, ...] {{Parameters}} * _SOFTWARE refers to software created surfaces or [[SCREEN]]s. -* _HARDWARE and _HARDWARE1 refer to surfaces created by GL hardware acceleration. -* _GLRENDER refers to GL code rendering order +* _HARDWARE and _HARDWARE1 refer to surfaces created by OpenGL hardware acceleration. +* _GLRENDER refers to OpenGL code rendering order {{PageDescription}} * The default on program start is: _DISPLAYORDER _SOFTWARE, _HARDWARE, _GLRENDER, _HARDWARE1 * Any content or combination order is allowed, except listing the same content twice consecutively. -* Simply using _DISPLAYORDER _HARDWARE will render hardware surfaces only. +* Simply using [[_DISPLAYORDER]] _HARDWARE will render hardware surfaces only. * Use an [[underscore]] to continue a code line on a new text row in the [[IDE]]. * After _DISPLAYORDER has been used, it must be used to make any changes, even to default. @@ -25,6 +25,10 @@ The '''_DISPLAYORDER''' statement defines the order to render software, hardware * Rendering the same content twice consecutively in a combination is not allowed. +==Availability== +* '''Version 1.000 and up.''' + + {{PageSeeAlso}} * [[_DISPLAY]] * [[_PUTIMAGE]] diff --git a/internal/help/_DISPLAY_(function).txt b/internal/help/_DISPLAY_(function).txt index ef5a979ea..513cb94f9 100644 --- a/internal/help/_DISPLAY_(function).txt +++ b/internal/help/_DISPLAY_(function).txt @@ -1,16 +1,17 @@ {{DISPLAYTITLE:_DISPLAY (function)}} -The '''_DISPLAY''' function returns the handle of the current image that is displayed on the screen. +The [[_DISPLAY]] function returns the handle of the current image that is displayed on the screen. {{PageSyntax}} -:''currentimage&'' = '''_DISPLAY''' +:{{Parameter|currentImage&}} = [[_DISPLAY]] -''Usage:'' -* Returns the current image handle value that is being displayed. Will return 0 if in the default [[SCREEN|screen]] image. -* Not to be confused with the [[_DISPLAY]] statement that displays the screen when not using {{KW|_AUTODISPLAY}}. +{{PageDescription}} +* Returns the current image handle value that is being displayed. Returns 0 if in the default [[SCREEN|screen]] image. +* Not to be confused with the [[_DISPLAY]] statement that displays the screen when not using [[_AUTODISPLAY]]. +{{PageExamples}} ''Example:'' Creating a mouse cursor using a page number that '''you create''' in memory without setting up page flipping. {{CodeStart}} {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) 'any graphics mode should work without setting up pages @@ -35,15 +36,15 @@ SetupCursor {{Cl|PCOPY}} 100, {{Cl|_DISPLAY (function)|_DISPLAY}} 'with the function return as destination page {{Cl|END SUB}} '' '' {{CodeEnd}} -''Note:'' Works with the '''_DISPLAY function''' return as the other page. If mouse reads are not crucial, put the [[_MOUSEINPUT]] loop inside of the UpdateCursor Sub. +''Note:'' Works with the '''_DISPLAY function''' return as the other page. If mouse reads are not crucial, put the [[_MOUSEINPUT]] loop inside of the UpdateCursor SUB. {{PageSeeAlso}} -* [[SCREEN]] {{text|(note the QB64 use of SCREEN to set which image to display)}} +* [[SCREEN]] * [[PCOPY]] * [[_DISPLAY]] {{text|(statement)}} * [[_AUTODISPLAY]] {{text|(default mode)}} -* [[_DISPLAYORDER]] {{text|(GL statement)}} +* [[_DISPLAYORDER]] {{text|(statement)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_DONTBLEND.txt b/internal/help/_DONTBLEND.txt index e1163dd55..4f79a2257 100644 --- a/internal/help/_DONTBLEND.txt +++ b/internal/help/_DONTBLEND.txt @@ -3,20 +3,21 @@ The [[_DONTBLEND]] statement turns off 32 bit alpha blending for the current ima {{PageSyntax}} -: '''_DONTBLEND''' [{{Parameter|imageHandle&}}] +: [[_DONTBLEND]] [{{Parameter|imageHandle&}}] {{Parameters}} * If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current [[_DEST]]ination write page. -''Usage:'' +{{PageDescription}} * If {{Parameter|imageHandle&}} is not valid, an [[ERROR Codes|Invalid handle]] error will occur. -* [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit! -* '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' -: Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opague. +* [[_DONTBLEND]] is faster than the default [[_BLEND]] unless you really need to use it in 32 bit. +* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +* Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque. +{{PageExamples}} ''Example 1:'' Use _DONTBLEND when you want the 32 bit screen surface to be opaque so that it covers up other backgrounds. [[CLS]] works too. {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(1280, 720, 32) @@ -88,7 +89,7 @@ ph = 0 {{Cl|_DISPLAY}} {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|LEN}}({{Cl|INKEY$}}) '' '' {{CodeEnd}}{{small|Code by Zom-B}} -''Explanation:'''To make the alpha image, turn alpha blending off. Otherwise PSET blends the pixel to instead of making the sprite transparent. +''Explanation:'' To make the alpha image, turn alpha blending off. Otherwise PSET blends the pixel to instead of making the sprite transparent. {{PageSeeAlso}} diff --git a/internal/help/_DONTWAIT.txt b/internal/help/_DONTWAIT.txt index a03e70b77..08d51a18a 100644 --- a/internal/help/_DONTWAIT.txt +++ b/internal/help/_DONTWAIT.txt @@ -1,17 +1,16 @@ {{DISPLAYTITLE:_DONTWAIT}} -[[_DONTWAIT]] is used with the {{KW|SHELL}} statement to specify that the program shouldn't wait until the SHELLed command/program is finished (which it otherwise does by default). +[[_DONTWAIT]] is used with the [[SHELL]] statement in '''QB64''' to specify that the program shouldn't wait until the external command/program is finished (which it otherwise does by default). {{PageSyntax}} -::: [[SHELL]] ['''_DONTWAIT'''] [{{Parameter|commandline$}}] +: [[SHELL]] [{{KW|_DONTWAIT}}] [{{Parameter|commandLine$}}] {{PageDescription}} -*Can only be used in the {{KW|SHELL}} statement when using '''QB64'''. -*Runs the command/program specified in {{Parameter|commandline$}} and lets the calling program continue at the same time in it's current screen format. +*Runs the command/program specified in {{Parameter|commandline$}} and lets the calling program continue at the same time in its current screen format. *Especially useful when CMD /C or START is used in a SHELL command line to run another program. * '''QB64''' automatically uses CMD /C or COMMAND /C when using SHELL. -* '''QB64''' program screens will not get distorted or minimized like Qbasic fullscreen modes could. +* '''QB64''' program screens will not get distorted or minimized like Qbasic fullscreen modes would. {{PageExamples}} diff --git a/internal/help/_ERRORLINE.txt b/internal/help/_ERRORLINE.txt index ea8176757..8bbb93697 100644 --- a/internal/help/_ERRORLINE.txt +++ b/internal/help/_ERRORLINE.txt @@ -1,7 +1,5 @@ {{DISPLAYTITLE:_ERRORLINE}} -The '''_ERRORLINE''' function returns the source code line number that caused the most recent runtime error. - - +The [[_ERRORLINE]] function returns the source code line number that caused the most recent runtime error. {{PageSyntax}} @@ -9,11 +7,12 @@ The '''_ERRORLINE''' function returns the source code line number that caused th {{PageDescription}} +* Used in program error troubleshooting. * Does not require that the program use line numbers as it counts the actual lines of code. -* The code line can be found using the QB64 IDE or any other text editor such as Notepad. -* Used in '''QB64''' program error troubleshooting ONLY. +* The code line can be found using the QB64 [[IDE]] (Use the shortcut '''Ctrl+G''' to go to a specific line) or any other text editor such as Notepad. +{{PageExamples}} ''Example:'' Displaying the current program line using a simulated [[ERROR]] code. {{CodeStart}} '' '' {{Cl|ON ERROR}} {{Cl|GOTO}} DebugLine 'can't use {{Cl|GOSUB}} @@ -29,6 +28,7 @@ DebugLine: {{PageSeeAlso}} * [[ON ERROR]] +* [[_INCLERRORLINE]], [[_INCLERRORFILE$]] * [[ERR]], [[ERL]] * [[ERROR]] * [[ERROR Codes]] diff --git a/internal/help/_EXIT_(function).txt b/internal/help/_EXIT_(function).txt index 4af858fc8..b2f865811 100644 --- a/internal/help/_EXIT_(function).txt +++ b/internal/help/_EXIT_(function).txt @@ -1,24 +1,25 @@ {{DISPLAYTITLE:_EXIT (function)}} -The '''_EXIT''' function prevents a program user exit and indicates if a user has clicked the close X window button or CTRL + BREAK. +The [[_EXIT]] function prevents the user from closing a program and indicates if a user has clicked the close button in the window title ('''X''' button) or used CTRL + BREAK. {{PageSyntax}} -:{{Parameter|quit%}} = _EXIT +:{{Parameter|exitSignal%}} = [[_EXIT]] {{PageDescription}} -* Once the _EXIT function is used, the program user can no longer manually exit the program until it ends. -* _EXIT returns any exit requests made AFTER the initial call as: -:: 0 = no exit request has been made since EXIT monitoring began in the program. -:: 1 = exit attempted by clicking the window X (close) box since last function call. (Bit 0 set) +* Once the [[_EXIT]] function is used, the user can no longer manually exit the program until it is ended with [[END]] or [[SYSTEM]]. +* [[_EXIT]] returns any exit requests made after the initial call as: +:: 0 = no exit request has been made since _EXIT monitoring began in the program. +:: 1 = exit attempted by clicking the window X (close) button since last function call. (Bit 0 set) :: 2 = exit attempted with CTRL + BREAK since last call. (Bit 1 set) :: 3 = both CTRL + BREAK and the X box have been used since last call. (Bit 0 and 1 set) * If a return value is not 0 the program can handle an exit request at a more convenient time if necessary. -* After a read, the _EXIT value is reset to 0 so store the value when a program delays an exit request. -* '''Note: Once _EXIT has been used once, you MUST monitor your program by checking it for user EXIT requests!''' -* Don't just use _EXIT once to prevent a user from exiting a program early! The user may NOT appreciate that! +* After being read, the _EXIT value is reset to 0 so store the value when a program delays an exit request. +* '''Note: Once _EXIT has been used once, you must monitor your program by checking it for user _EXIT requests.''' +* Don't just use _EXIT once to prevent a user from exiting a program early, as that constitutes bad practice. +{{PageExamples}} ''Example 1:'' Using an ON TIMER check to read the _EXIT request return values. {{CodeStart}} '' '' q = {{Cl|_EXIT (function)|_EXIT}} 'function read prevents any program exit at start of program @@ -58,9 +59,9 @@ LOOP '' '' {{PageSeeAlso}} -* [[SYSTEM]] {{text|(ends a program immediately and closes the window in QB64 or a Qbasic program run from the command line, not IDE.)}} -* [[END]] {{text|(ends a program displaying "Press any key to continue...".)}} -* [[EXIT]] {{text|(exits a loop, SUB or FUNCTION when used before [[DO]], [[FOR]], [[WHILE]], [[SUB]] or [[FUNCTION]])}} +* [[SYSTEM]] +* [[END]] +* [[EXIT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_FILEEXISTS.txt b/internal/help/_FILEEXISTS.txt index 01c2e8b42..183ec51ad 100644 --- a/internal/help/_FILEEXISTS.txt +++ b/internal/help/_FILEEXISTS.txt @@ -1,24 +1,32 @@ {{DISPLAYTITLE:_FILEEXISTS}} -The '''_FILEEXISTS''' function determines if a designated file name exists and returns True or False. +The '''_FILEEXISTS''' function determines if a designated file name exists and returns true (-1) or false (0). {{PageSyntax}} - -::: IF _FILEEXISTS(''filename$'') THEN +: {{Parameter|theFileExists%}} = [[_FILEEXISTS]]({{Parameter|filename$}}) -* The ''filename'' parameter can be a literal or variable [[STRING|string]] value that can include a path. +{{PageDescription}} +* The {{Parameter|filename$}} parameter can be a literal or variable [[STRING|string]] value that can include a path. * The function returns -1 when a file exists and 0 when it does not. * The function reads the system information directly without using a [[SHELL]] procedure. * The function will use the appropriate Operating System path separators. [[_OS$]] can determine the operating system. -* '''This function does not guarantee that a file can be accessed or opened, just that it exists''' +* '''This function does not guarantee that a file can be accessed or opened, just that it exists.''' -''See also:'' +{{PageExamples}} +{{Parameter|Example:'' Checks if a file exists before opening it. +{{CodeStart}} +{{Cl|IF}} {{Cl|_FILEEXISTS}}("mysettings.ini") THEN + {{Cl|PRINT}} "Settings file found." +{{Cl|END IF}} +{{CodeEnd}}}} + + +{{PageSeeAlso}} * [[_DIREXISTS]], [[_OS$]] * [[SHELL]], [[FILES]] * [[KILL]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_FLOAT.txt b/internal/help/_FLOAT.txt index 76a5724d4..789cd89eb 100644 --- a/internal/help/_FLOAT.txt +++ b/internal/help/_FLOAT.txt @@ -3,27 +3,27 @@ {{PageSyntax}} -::[[DIM]] {{Parameter|variable}} AS '''_FLOAT''' +::[[DIM]] {{Parameter|variable}} AS [[_FLOAT]] {{PageDescription}} * '''QB64''' always allocates 32 bytes to store this value. -* It is safe to assume this value is at least as precise as {{KW|DOUBLE}}. +* It is safe to assume this value is at least as precise as [[DOUBLE]]. * Under the current implementation it is stored in a 10-byte floating point variable. -* '''_FLOAT''' variables can also use the ## variable name type suffix. +* [[_FLOAT]] variables can also use the ## variable name type suffix. * Values returned may be expressed using exponential or [[scientific notation]] using '''E''' for SINGLE or '''D''' for DOUBLE precision. -* According to [http://babbage.cs.qc.edu/courses/cs341/IEEE-754references.html IEEE-754] this can store a value of up to 1.1897E+4932 compared to a DOUBLE which 'only' goes up to 1.7976E+308. -* Floating decimal point numerical values cannot be {{KW|_UNSIGNED}}! +* According to [http://babbage.cs.qc.edu/courses/cs341/IEEE-754references.html IEEE-754] this can store a value of up to 1.1897E+4932 compared to a DOUBLE which goes up to 1.7976E+308. +* Floating decimal point numerical values cannot be [[_UNSIGNED]]. * Values can be converted to 32 byte [[ASCII]] strings using [[_MK$]] and back with [[_CV]]. * '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' -* Note: A _GL_FLOAT is a [[SINGLE]] (4 byte) floating point number, a QB64 _FLOAT is a 10-byte floating point number. +* Note: OpenGL's [[_GL_FLOAT]] constant is a [[SINGLE]] (4 byte) floating point number, while a native QB64 _FLOAT is a 10-byte floating point number. {{PageSeeAlso}} * [[DOUBLE]], [[SINGLE]] * [[_MK$]], [[_CV]] * [[_DEFINE]], [[DIM]] -* [[PDS(7.1) Procedures#CURRENCY|CURRENCY]] +* [[PDS (7.1) Procedures#CURRENCY|CURRENCY]] * [[Variable Types]] diff --git a/internal/help/_FONT.txt b/internal/help/_FONT.txt index 82ab543c9..e97a416ec 100644 --- a/internal/help/_FONT.txt +++ b/internal/help/_FONT.txt @@ -1,30 +1,31 @@ {{DISPLAYTITLE:_FONT}} -The '''_FONT''' statement sets the current [[_LOADFONT]] function font handle to be used by [[PRINT]]. +The [[_FONT]] statement sets the current [[_LOADFONT]] function font handle to be used by [[PRINT]]. {{PageSyntax}} -::: '''_FONT ''Font_handle'''''[, ''Image_handle&''] +: [[_FONT]] {{Parameter|fontHandle&}}[, {{Parameter|imageHandle&}}] {{Parameters}} -* {{Parameter|Font_handle}} is the handle retrieved from {{KW|_LOADFONT}} function, the {{KW|_FONT (function)|_FONT}} function, or a predefined handle. +* {{Parameter|fontHandle&}} is the handle retrieved from [[_LOADFONT]] function, the [[_FONT (function)|_FONT]] function, or a predefined handle. * If the image handle is omitted the current image [[_DEST]]ination is used. Zero can designate the current program [[SCREEN]]. -''Usage:'' +{{PageDescription}} * Predefined '''QB64''' font handle numbers can be used before freeing a font: **'''_FONT 8 ''' - default font for [[SCREEN (statement)|SCREEN]] 1, 2, 7, 8 or 13 **'''_FONT 14''' - default font for [[SCREEN (statement)|SCREEN]] 9 or 10 -**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ({{KW|WIDTH}} 80, 25 text only), 11 or 12 +**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ([[WIDTH]] 80, 25 text only), 11 or 12 **'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0 only'''. -* {{KW|Unicode}} characters can be assigned to a monospace font that contains those unicode characters using the {{KW|_MAPUNICODE}} TO {{KW|ASCII}} mapping statement. The optional '''IME cyberbit.ttf''' font included with QB64 can also be used. -* Can alpha blend a font with a background screen created by {{KW|_NEWIMAGE}} in 32 bit color. -* '''Check for valid handle values greater than 0 before using or freeing font handles!''' -* Free '''unused''' font handles with {{KW|_FREEFONT}}. Freeing invalid handles will create an [[ERROR Codes|"illegal function call"]] error! -* '''NOTE: SCREEN 0 can only use ONE font type and style per viewed SCREEN page! Font size may also affect the window size.''' +* [[Unicode]] characters can be assigned to a monospace font that contains those unicode characters using the [[_MAPUNICODE]] TO [[ASCII]] mapping statement. The optional '''IME cyberbit.ttf''' font included with QB64 can also be used. +* Can alpha blend a font with a background screen created by [[_NEWIMAGE]] in 32 bit color. +* '''Check for valid handle values greater than 0 before using or freeing font handles.''' +* Free '''unused''' font handles with [[_FREEFONT]]. Freeing invalid handles will create an [[ERROR Codes|"illegal function call"]] error. +* '''NOTE: SCREEN 0 can only use one font type and style per viewed SCREEN page. Font size may also affect the window size.''' -''Example:'' Previewing a font in SCREEN 0. A different true type font can be substituted. +{{PageExamples}} +''Example:'' Previewing a font in SCREEN 0. A different true type font can be substituted below. {{CodeStart}} fontpath$ = {{Cl|ENVIRON$}}("SYSTEMROOT") + "\fonts\lucon.ttf" 'Find Windows Folder Path. diff --git a/internal/help/_FONTHEIGHT.txt b/internal/help/_FONTHEIGHT.txt index a72d32a5f..36c5e38ac 100644 --- a/internal/help/_FONTHEIGHT.txt +++ b/internal/help/_FONTHEIGHT.txt @@ -1,16 +1,18 @@ {{DISPLAYTITLE:_FONTHEIGHT}} -The '''_FONTHEIGHT''' function returns the font height of a font handle created by [[_LOADFONT]]. +The [[_FONTHEIGHT]] function returns the font height of a font handle created by [[_LOADFONT]]. {{PageSyntax}} -:{{Parameter|pixel_height%}} = {{KW|_FONTHEIGHT}}[({{Parameter|font_handle}})] +:{{Parameter|pixelHeight%}} = [[_FONTHEIGHT]][({{Parameter|fontHandle&}})] -* Will return height of the last font used if a handle is not designated. -* If no font is used it returns the current screen mode's text block height. +{{PageDescription}} +* Returns the height of the last font used if a handle is not designated. +* If no font is set it returns the current screen mode's text block height. +{{PageExamples}} ''Example:'' Finding the [[_FONT|font]] or text block size of printed [[STRING|string]] characters in graphic [[SCREEN]] modes. {{CodeStart}} '' '' DO diff --git a/internal/help/_FONTWIDTH.txt b/internal/help/_FONTWIDTH.txt index 136748236..7f8ab9b8d 100644 --- a/internal/help/_FONTWIDTH.txt +++ b/internal/help/_FONTWIDTH.txt @@ -1,14 +1,14 @@ {{DISPLAYTITLE:_FONTWIDTH}} -The '''_FONTWIDTH''' function returns the font width of a MONOSPACE font handle created by {{KW|_LOADFONT}}. +The [[_FONTWIDTH]] function returns the font width of a MONOSPACE font handle created by [[_LOADFONT]]. {{PageSyntax}} -:{{Parameter|pixel_width%}} = {{KW|_FONTWIDTH}}[({{Parameter|font_handle}})] +:{{Parameter|pixelWidth%}} = [[_FONTWIDTH]][({{Parameter|fontHandle&}})] -* Will return width of last font used if a handle is not designated. -* '''Variable width fonts always return width 0.''' Even fixed width fonts will return 0 unless the "MONOSPACE" style option is used. -* '''"MONOSPACE" cannot be used on a variable width font.''' +* Returns the character width of the last font used if a handle is not specified. +* '''Variable width fonts always return {{Parameter|pixelWidth%}} = 0.''' Even fixed width fonts return 0 unless the [[LOADFONT|"MONOSPACE"]] style option is used. +* QB64 '''version 1.000 and up''' can load a variable width font as monospaced with the [[LOADFONT|"MONOSPACE"]] style parameter. * The font width is generally 3/4 of the [[_FONTHEIGHT]] specified when loading the font. * In '''graphics''' [[SCREEN (statement)|screen]] modes, [[_PRINTWIDTH]] can return the total '''pixel width''' of a literal or variable [[STRING|string]] of text. @@ -20,5 +20,4 @@ The '''_FONTWIDTH''' function returns the font width of a MONOSPACE font handle * [[_PRINTWIDTH]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_FONT_(function).txt b/internal/help/_FONT_(function).txt index 73b2d4141..4b3710d44 100644 --- a/internal/help/_FONT_(function).txt +++ b/internal/help/_FONT_(function).txt @@ -1,19 +1,18 @@ {{DISPLAYTITLE:_FONT (function)}} -The '''_FONT''' function creates a new alphablended font handle from a designated image handle created by {{KW|_NEWIMAGE}} in 32 bit color. - +The [[_FONT]] function retrieves the font handle from the specified image handle or the current [[_DEST]]ination page's font. {{PageSyntax}} -:{{Parameter|font_handle}} = {{KW|_FONT}}[({{Parameter|image_handle}})] +:{{Parameter|fontHandle&}} = [[_FONT]][({{Parameter|imageHandle&}})] {{PageDescription}} -*font_handle is the newly created handle that points to the font. -*image_handle is the handle to the image which you want to retrieve the font from. +*imageHandle& is the handle to the image which you want to retrieve the font from. If not specified, it is assumed to be the current [[_DEST]]ination page. {{PageSeeAlso}} *[[_LOADFONT]], [[_FONT]] +*[[_DEST]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_FREEFONT.txt b/internal/help/_FREEFONT.txt index d69c7f418..aedd56e4d 100644 --- a/internal/help/_FREEFONT.txt +++ b/internal/help/_FREEFONT.txt @@ -1,22 +1,25 @@ {{DISPLAYTITLE:_FREEFONT}} -The '''_FREEFONT''' statement frees a font handle that was created by {{KW|_LOADFONT}}. +The [[_FREEFONT]] statement frees a font handle that was created by [[_LOADFONT]]. -{{PageSyntax}}: '''_FREEFONT ('''font_handle&''')''' +{{PageSyntax}} +:[[_FREEFONT]] ({{Parameter|fontHandle&}}) -* Unloads fonts that are no longer used or needed later to free program memory and resources. -* You cannot free a font which is in use. Change the font to a QB64 default font size before freeing the handle(see example). +{{PageDescription}} +* Unloads fonts that are no longer in use or needed in order to free program memory and resources. +* You cannot free a font which is in use. Change the font to a QB64 default font size before freeing the handle (see example below). * Predefined '''QB64''' font handle numbers can be used before freeing a font: **'''_FONT 8 ''' - default font for [[SCREEN (statement)|SCREEN]] 1, 2, 7, 8 or 13 **'''_FONT 14''' - default font for [[SCREEN (statement)|SCREEN]] 9 or 10 **'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ({{KW|WIDTH}} 80, 25 text only), 11 or 12 -**'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0 only'''. -* If the font handle is invalid(equals -1 or 0), an [[ERROR Codes|error]] will occur! '''Check handle values before using or freeing them!''' -* You cannot free inbuilt/default QB64 fonts nor do they ever need freed! +**'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0'''. +* If the font handle is invalid (equals -1 or 0), an [[ERROR Codes|error]] will occur. '''Check handle values before using or freeing them.''' +* You cannot free inbuilt/default QB64 fonts nor do they ever need freed. +{{PageExamples}} ''Example 1:'' Previews and creates a file list of valid MONOSPACE TTF fonts by checking the [[_LOADFONT]] handle values. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 12 @@ -88,7 +91,7 @@ ClearFont: {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_FONT]] * [[_LOADFONT]] diff --git a/internal/help/_FREEIMAGE.txt b/internal/help/_FREEIMAGE.txt index ba3047d25..6811ca9f6 100644 --- a/internal/help/_FREEIMAGE.txt +++ b/internal/help/_FREEIMAGE.txt @@ -3,33 +3,28 @@ The '''_FREEIMAGE''' statement releases the designated file image created by the {{PageSyntax}} -::: '''_FREEIMAGE''' [handle&] +: [[_FREEIMAGE]] [{{Parameter|handle&}}] {{PageDescription}} -*If {{Parameter|handle}} is omitted, the current destination image is freed from memory. '''Do NOT free the current program SCREEN mode!''' +*If {{Parameter|handle&}} is omitted, the current destination image is freed from memory. *Freeing the destination image or source image will result in the display page being selected instead. -*'''Invalid image handle values of -1 or 0 cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur!'''! Check the value! -* '''[[SCREEN]] modes in use cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur!''' Change SCREEN modes before freeing. +*'''Invalid image handle values of -1 or 0 cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur.''' Check the handle value first. +* '''[[SCREEN]] modes in use cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur.''' Change SCREEN modes before freeing. *Once a specific image handle is no longer used or referenced by your program, it can be freed with [[_FREEIMAGE]]. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' -* '''It is IMPORTANT to free unused or uneeded images with [[_FREEIMAGE]] to prevent memory overflow errors!''' -* '''Do NOT try to free image handles currently being used as the active [[SCREEN]]! Change screen modes first.''' - +* '''It is important to free unused or unneeded images with [[_FREEIMAGE]] to prevent memory overflow errors.''' +* '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.''' +{{PageExamples}} ''Example:'' Loading a program splash screen and freeing image when no longer necessary: {{CodeStart}} '' '' s& = {{Cl|_LOADIMAGE}}("SPLASH.BMP",32) 'load 32 bit(24 BPP) image - {{Cl|IF}} s& < -1 THEN {{Cl|SCREEN (statement)|SCREEN}} s& 'use image as a 32 bit SCREEN - {{Cl|_DELAY}} 6 'display splash screen for 6 seconds - {{Cl|SCREEN (statement)|SCREEN}} 0 'MUST change screen mode before freeing a SCREEN image! - {{Cl|IF}} s& < -1 THEN {{Cl|_FREEIMAGE}} s& 'handle value MUST be less than -1 or error! - {{Cl|CLS}} '' '' {{CodeEnd}} : ''Note:'' A valid image file name must be used by [[_LOADIMAGE]] or the invalid handle memory value will not need to be freed. diff --git a/internal/help/_FREETIMER.txt b/internal/help/_FREETIMER.txt index aaceedeba..72bd8aabc 100644 --- a/internal/help/_FREETIMER.txt +++ b/internal/help/_FREETIMER.txt @@ -1,13 +1,13 @@ {{DISPLAYTITLE:_FREETIMER}} -The '''_FREETIMER''' function returns a free {{KW|TIMER}} number for multiple {{KW|ON TIMER(n)}} events. +The [[_FREETIMER]] function returns a free [[TIMER]] number for multiple [[ON TIMER(n)]] events. {{PageSyntax}} -: timerhandle% = {{KW|_FREETIMER}} +: {{Parameter|timerhandle%}} = [[_FREETIMER]] {{PageDescription}} -* QB64 can use an unlimited number of ON TIMER (number, seconds!) event {{KW|INTEGER}} values at once. +* QB64 can use an unlimited number of ON TIMER (number, seconds!) event [[INTEGER]] values at once. * Every time _FREETIMER is called the [[INTEGER]] value returned will increase by one, starting at 1, whether it is used or not. * Store multiple returns in different variable names to refer to separate events later. diff --git a/internal/help/_FULLSCREEN.txt b/internal/help/_FULLSCREEN.txt index 1fba85f64..464ebd3d0 100644 --- a/internal/help/_FULLSCREEN.txt +++ b/internal/help/_FULLSCREEN.txt @@ -1,26 +1,28 @@ {{DISPLAYTITLE:_FULLSCREEN}} -The '''_FULLSCREEN''' statement attempts to make the program window fullscreen. +The [[_FULLSCREEN]] statement attempts to make the program window fullscreen. {{PageSyntax}} -:::'''_FULLSCREEN''' [{''_STRETCH | _SQUAREPIXELS| _OFF''}] +:[[_FULLSCREEN]] [''_STRETCH | _SQUAREPIXELS| _OFF''][, ''_SMOOTH''] -''Optional'' {{Parameters}} +{{Parameters}} * {{Parameter|_STRETCH}} default first choice attempts to mimic QBasic's full screens if possible. [[_FULLSCREEN (function)]] returns 1. * {{Parameter|_SQUAREPIXELS}} alternate choice enlarges the pixels into squares on some monitors. [[_FULLSCREEN (function)|_FULLSCREEN]] returns 2 * {{Parameter|_OFF}} turns _FULLSCREEN off after full screen has been enabled. [[_FULLSCREEN (function)]] returns 0. +* Second optional parameter ''_SMOOTH'' applies antialiasing to the stretched screen. {{PageDescription}} -* '''Set the [[SCREEN]] mode and text [[WIDTH]] when necessary FIRST!''' Otherwise there may be desktop view issues. -* _FULLSCREEN alone chooses {{Parameter|_STRETCH}} or {{Parameter|_SQUAREPIXELS}} (prioritizes _STRETCH to mimic QBASIC if possible) -* '''Check the fullscreen mode with the [[_FULLSCREEN (function)|_FULLSCREEN]] function in your programs when a method is required! +* '''Set the [[SCREEN]] mode and text [[WIDTH]] when necessary first.''' Otherwise there may be desktop view issues. +* _FULLSCREEN with no parameters chooses {{Parameter|_STRETCH}} or {{Parameter|_SQUAREPIXELS}} (prioritizes _STRETCH to mimic QBasic if possible) +* '''Check the fullscreen mode with the [[_FULLSCREEN (function)|_FULLSCREEN]] function in your programs when a method is required. * It is advisable to get [[INPUT|input]] from the user to confirm that fullscreen was completed or there were possible monitor incompatibilities. -* If fullscreen is '''not confirmed''' with a [[_FULLSCREEN (function)]] return '''greater than 0''', then disable with '''_FULLSCREEN _OFF'''! -* '''NOTE:''' _FULLSCREEN can also be affected by custom [[_FONT]] size settings and make program screens too large! +* If fullscreen is '''not confirmed''' with a [[_FULLSCREEN (function)]] return '''greater than 0''', then disable with '''_FULLSCREEN _OFF'''. +* '''NOTE:''' _FULLSCREEN can also be affected by custom [[_FONT]] size settings and make program screens too large. +{{PageExamples}} ''Example 1:'' Setting the screen mode first prevents enlargement of the desktop before the program window is set: {{CodeStart}} {{Cl|SCREEN}} 12 @@ -96,7 +98,31 @@ ClearFont: {{CodeEnd}} - +''Example 3:'' Testing all fullscreen methods. +{{CodeStart}} +{{Cl|PRINT}} "Hello, world!" +{{Cl|PRINT}} "Hit 1 for windowed mode; +{{Cl|PRINT}} " 2 for _STRETCH" +{{Cl|PRINT}} " 3 for _SQUAREPIXELS" +{{Cl|PRINT}} " 4 for _STRETCH, _SMOOTH" +{{Cl|PRINT}} " 5 for _SQUAREPIXELS, _SMOOTH" +{{Cl|DO}} + k$ = {{Cl|INKEY$}} + {{Cl|SELECT CASE}} {{Cl|VAL}}(k$) + {{Cl|CASE}} 1 + {{Cl|_FULLSCREEN}} _OFF + {{Cl|CASE}} 2 + {{Cl|_FULLSCREEN}} _STRETCH + {{Cl|CASE}} 3 + {{Cl|_FULLSCREEN}} _SQUAREPIXELS + {{Cl|CASE}} 4 + {{Cl|_FULLSCREEN}} _STRETCH, _SMOOTH + {{Cl|CASE}} 5 + {{Cl|_FULLSCREEN}} _SQUAREPIXELS, _SMOOTH + {{Cl|END}} {{Cl|SELECT}} + {{Cl|_LIMIT}} 30 +{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|_EXIT (function)|_EXIT}} +{{Cl|SYSTEM}}{{CodeEnd}} {{PageSeeAlso}} diff --git a/internal/help/_FULLSCREEN_(function).txt b/internal/help/_FULLSCREEN_(function).txt index 100777130..da6dfcb5e 100644 --- a/internal/help/_FULLSCREEN_(function).txt +++ b/internal/help/_FULLSCREEN_(function).txt @@ -1,23 +1,22 @@ {{DISPLAYTITLE:_FULLSCREEN (function)}} -The '''_FULLSCREEN''' function returns the present full screen mode setting of the screen window. +The [[_FULLSCREEN]] function returns the present full screen mode setting of the screen window. -{{PageSyntax}}: full% = {{KW|_FULLSCREEN (function)|_FULLSCREEN}} +{{PageSyntax}} +: {{Parameter|full%}} = [[_FULLSCREEN (function)|_FULLSCREEN]] -* ''Function Returns:'' +{{PageDescription}} +* ''Function returns:'' ** 0 = _OFF (any positive non-0 value means fullscreen is on) ** 1 = _STRETCH ** 2 = _SQUAREPIXELS +* It '''cannot''' be assumed that calling [[_FULLSCREEN]] will succeed. It cannot be assumed that the type of full screen will match the requested one. '''Always check the [[_FULLSCREEN (function)]] return in your programs.''' +* '''Warning:''' Despite your software, the user's hardware, drivers and monitor may not function in some modes. Thus, it is highly recommended that you manually confirm with the user whether the switch to full screen was successful. This can be done "quietly" in some cases by getting the user to click on a button on screen with their mouse or press an unusual key. If the user does not respond after about 8 seconds, switch them back to windowed mode. +<center>'''Using large fonts with [[_FULLSCREEN]] can cause monitor or Windows Desktop problems or kill a program.'''</center> -It '''cannot''' be assumed that calling [[_FULLSCREEN]] will succeed. It cannot be assumed that the type of full screen will match the requested one. '''Always check the [[_FULLSCREEN (function)]] return in your programs!''' - - -'''Warning:''' Despite your software, the user's hardware, drivers and monitor may not function in some modes. Thus, it is highly recommended that you manually confirm with the user whether the switch to full screen was successful. This can be done "quietly" in some cases by getting the user to click on a button on screen with their mouse or press an unusual key. If the user does not respond after about 8 seconds, switch them back to windowed mode. -<center>'''BEWARE: Using LARGE FONTS with [[_FULLSCREEN]] can cause monitor or Windows Desktop problems or kill a program!'''</center> - - +{{PageExamples}} ''Example:'' Shows how fonts and the _FULLSCREEN mode can resize a program window. {{CodeStart}} '' '' @@ -97,11 +96,10 @@ f& = currentf& {{CodeEnd}} -''Explanation:'' The '''_FULLSCREEN''' function can avoid screen display and monitor problems when used to monitor the success of the full screen operation! If a full screen mode is '''NOT''' achieved (the function will return 0), '''turn it OFF!''' +''Explanation:'' The '''_FULLSCREEN''' function can avoid screen display and monitor problems when used to monitor the success of the full screen operation. If a full screen mode is '''not''' achieved (the function will return 0), '''call [[_FULLSCREEN]] OFF''' {{PageSeeAlso}} - * [[_FULLSCREEN]] (statement) * [[_SCREENMOVE]], [[_SCREENX]], [[_SCREENY]] diff --git a/internal/help/_G2D.txt b/internal/help/_G2D.txt index fc53d6e87..a9948f2ad 100644 --- a/internal/help/_G2D.txt +++ b/internal/help/_G2D.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_G2D}} -The '''_G2D''' function converts a GRADIENT value into a DEGREE value. +The [[_G2D]] function converts a '''gradient''' value into a '''degree''' value. {{PageSyntax}} -:: result = [[_G2D]](''num'') +: {{Parameter|result}} = [[_G2D]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Gradients into Degree. {{CodeStart}} INPUT "Give me an angle in Gradients ", D @@ -21,11 +23,10 @@ That angle in Degrees is 54 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]], [[_D2R]] * [[_G2R]] * [[_R2D]], [[_R2G]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_G2R.txt b/internal/help/_G2R.txt index 88e5f74b9..803c0a09b 100644 --- a/internal/help/_G2R.txt +++ b/internal/help/_G2R.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_G2R}} -The '''_G2R''' function converts a GRADIENT value into a RADIAN value. +The [[_G2R]] function converts a '''gradient''' value into a '''radian''' value. {{PageSyntax}} -:: result = [[_G2R]](''num'') +: {{Parameter|result}} = [[_G2R]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Gradient into Radians. {{CodeStart}} INPUT "Give me an angle in Gradient ", D @@ -21,11 +23,10 @@ That angle in Radians is .9424778 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]], [[_D2R]] * [[_G2D]], [[_G2R]] * [[_R2D]], [[_R2G]] - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_GREEN.txt b/internal/help/_GREEN.txt index f465dd656..331dc0efb 100644 --- a/internal/help/_GREEN.txt +++ b/internal/help/_GREEN.txt @@ -3,7 +3,7 @@ The [[_GREEN]] function returns the palette index or the green component intensi {{PageSyntax}} -:: greenintensity& = '''_GREEN('''{{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]''')''' +: {{Parameter|greenIntensity&}} = [[_GREEN]]({{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]) {{PageDescription}} @@ -11,15 +11,15 @@ The [[_GREEN]] function returns the palette index or the green component intensi * The [[LONG]] intensity value returned ranges from 0 (no intensity, not present) to 255 (full intensity). * If {{Parameter|imageHandle&}} specifies a 32-bit color image, {{Parameter|rgbaColorIndex&}} is interpreted as a 32-bit ''RGBA'' color value. * If {{Parameter|imageHandle&}} specifies an image that uses a palette, {{Parameter|rgbaColorIndex&}} is interpreted as a palette index. -* If {{Parameter|imageHandle&}} is not specified, it is assumed to be the current write page. +* If {{Parameter|imageHandle&}} is not specified, it is assumed to be the current write page (See [[_DEST]]). * If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error will occur. * If {{Parameter|rgbaColorIndex&}} is outside the range of valid indexes for a given image mode, an [[ERROR Codes|illegal function call]] error occurs. -* Uses index parameters passed by the {{KW|_RGB}}, {{KW|_RGBA}}, {{KW|_RGB32}} or {{KW|_RGBA32}} functions. +* Uses index parameters passed by the [[_RGB]], [[_RGBA]], [[_RGB32]] or [[_RGBA32]] functions. * An image handle is optional. -''See Example:'' -* [[POINT]] +{{PageExamples}} +* See example in [[POINT]]. {{PageSeeAlso}} diff --git a/internal/help/_GREEN32.txt b/internal/help/_GREEN32.txt index 525f5e997..37a3dbefd 100644 --- a/internal/help/_GREEN32.txt +++ b/internal/help/_GREEN32.txt @@ -1,9 +1,9 @@ {{DISPLAYTITLE:_GREEN32}} -The [[_GREEN32]] function ALWAYS returns the green component intensity of a 32-bit image or surface color. +The [[_GREEN32]] function returns the green component intensity of a 32-bit image or surface color. {{PageSyntax}} -:: green32color& = '''_GREEN32('''{{Parameter|rgbaColor&}}''')''' +: green32color& = [[_GREEN32]]({{Parameter|rgbaColor&}}) {{PageDescription}} @@ -12,8 +12,8 @@ The [[_GREEN32]] function ALWAYS returns the green component intensity of a 32-b * [[LONG]] intensity values returned range from 0 (no intensity, not present) to 255 (full intensity). -''See Example:'' -* [[POINT]] +{{PageExamples}} +* See example in [[POINT]]. {{PageSeeAlso}} diff --git a/internal/help/_HIDE.txt b/internal/help/_HIDE.txt index bb965e7a7..f2d6600cf 100644 --- a/internal/help/_HIDE.txt +++ b/internal/help/_HIDE.txt @@ -1,18 +1,19 @@ {{DISPLAYTITLE:_HIDE}} -The '''_HIDE''' action is used to hide the DOS window opened by a [[SHELL]] statement. +The [[_HIDE]] action is used to hide the console window opened by a [[SHELL]] statement. {{PageSyntax}} -::: [[SHELL]] ['''_HIDE'''] {{Parameter|StringCommandLine$}} +: [[SHELL]] ['''_HIDE'''] {{Parameter|StringCommandLine$}} -* Can only be used in the {{KW|SHELL}} statement when using '''QB64'''. -* Allows any DOS command line window to be hidden from view without affecting the program. -* {{KW|_HIDE}} MUST be used when sending("piping") screen information to a file! +{{PageDescription}} +* Allows any command line window to be hidden from view without affecting the program. +* [[_HIDE]] must be used when sending ("piping") screen information to a file. * '''Note:''' Some commands may not work without adding CMD /C to the start of the command line. -''Example:'' Subprogram that displays long and short filenames using the DIR /X option(NT or above) in SCREEN 12: +{{PageExamples}} +''Example:'' Subprogram that displays long and short filenames using the DIR /X option (WindowsNT or above) in SCREEN 12: {{CodeStart}} '' '' SUB LFN @@ -55,7 +56,7 @@ END SUB '' '' {{PageSeeAlso}} * [[SHELL]], [[_DONTWAIT]] -* [[FILELIST$ (function)]] (member [[FILES]] function) +* [[FILELIST$ (function)]] ([[FILES]] function, member-contributed) {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_ICON.txt b/internal/help/_ICON.txt index 5c224127d..f05682ffd 100644 --- a/internal/help/_ICON.txt +++ b/internal/help/_ICON.txt @@ -1,42 +1,44 @@ {{DISPLAYTITLE:_ICON}} -The '''_ICON''' statement uses an image handle from [[_LOADIMAGE]] for the program header and GL icon image in the OS. +The [[_ICON]] statement uses an image handle from [[_LOADIMAGE]] for the program header and icon image in the OS. {{PageSyntax}} -: [[_ICON]] [''mainimagehandle&''[, ''smallimagehandle&'']] +: [[_ICON]] [{{Parameter|mainImageHandle&}}[, {{Parameter|smallImageHandle&}}]] {{Parameters}} -* ''mainimagehandle'' is the [[LONG]] handle value of the OS icon and title bar image pre-loaded with [[_LOADIMAGE]] when used alone. -* ''smallimagehandle'' is the [[LONG]] handle value of a different title bar image pre-loaded with [[_LOADIMAGE]] when used. +* {{Parameter|mainImageHandle&}} is the [[LONG]] handle value of the OS icon and title bar image pre-loaded with [[_LOADIMAGE]] when used alone. +* {{Parameter|smallImageHandle&}} is the [[LONG]] handle value of a different title bar image pre-loaded with [[_LOADIMAGE]] when used. +* No image handle designates use of the default QB64 icon or the embedded icon set by [[$EXEICON]]. {{PageDescription}} -* Older SDL versions must use a valid image handle created by [[_LOADIMAGE]]. The default QB64 icon will appear otherwise. -* In '''QB64 GL''' no image handle denotes that the default QB64 program icon should be used. -:::''mainimagehandle'' will create the image as the icon in the OS and the image in the program header. -:::''smallimagehandle'' can be used for a different image in the program header bar. +* If no image handle is passed, the default QB64 icon will be used (all versions). If the [[$EXEICON]] metacommand is used, [[_ICON]] without an image handle uses the embedded icon from the binary (Windows only). +* Beginning with '''version 1.000''', the following is considered: +:::{{Parameter|mainImageHandle&}} creates the image as the icon in the OS and the image in the program header (title bar). +:::{{Parameter|smallImageHandle&}} can be used for a different image in the program header bar. *The header image will automatically be resized to fit the icon size of 16 X 16 if smaller or larger. -*Once the program's icon is set, the image can be discarded with [[_FREEIMAGE]]. +*Once the program's icon is set, the image handle can be discarded with [[_FREEIMAGE]]. {{PageErrors}} -* '''NOTE: QB64 SDL does not support icon files! An error will occur using [[_LOADIMAGE]]! See Example 2.''' +* '''NOTE: Icon files are not supported with [[_LOADIMAGE]] and an error will occur. See Example 2.''' * Images used can be smaller or larger than 32 X 32 pixels, but image resolution may be affected. -* It is IMPORTANT to free unused or uneeded images with [[_FREEIMAGE]] to prevent memory overflow errors! -*'''SCREEN 0 text mode requires a 32 bit palette in [[_LOADIMAGE]] to load images other than icons as program icons.''' +* It is important to free unused or uneeded images with [[_FREEIMAGE]] to prevent memory overflow errors. +*In '''SCREEN 0''' (default text mode) you need to specify 32-bit mode in [[_LOADIMAGE]] to load images.''' +{{PageExamples}} ''Example 1:'' Loading an image to a 32 bit palette in SCREEN 0 (the default screen mode). {{CodeStart}} '' '' -i& ={{Cl|_LOADIMAGE}}("RDSWU16.BMP",32) '<<<<<<< use your image file name here +i& ={{Cl|_LOADIMAGE}}("RDSWU16.BMP", 32) '<<<<<<< use your image file name here {{Cl|IF}} i& < -1 THEN {{Cl|_ICON}} i& {{Cl|_FREEIMAGE}} i& ' release image handle after setting icon {{Cl|END IF}} {{CodeEnd}} -:''Note:'' _ICON images can be freed if the [[SCREEN]] mode stays the same. Freed image handles can on longer be referenced! +:''Note:'' _ICON images can be freed if the [[SCREEN]] mode stays the same. Freed image handles can on longer be referenced. ''Example 2:'' Function that converts an icon into a temporary bitmap for use in QB64. Function returns the available image count. @@ -118,13 +120,13 @@ Icon2BMP = count ' return the number of icons available in the icon : ''Note:'' Once the file has been loaded into memory, the image handle can still be used even after the file has been deleted. -''See also:'' +{{PageSeeAlso}} * [[_TITLE]] * [[_LOADIMAGE]] -* [[Creating Icon Bitmaps]] (member program) +* [[$EXEICON]], [[Embedding Icons in EXE|Manually Embedding Icons in .EXE]] {{text|(for versions of QB64 prior to 1.000)}} +* [[Creating Icon Bitmaps]] {{text|(member-contributed program)}} * [[Bitmaps]], [[Icons and Cursors]] * [[Resource_Table_extraction#Extract_Icon|Icon Extraction]] -* [[Embedding Icons in EXE]] {{text|(Icons viewed in Windows Explorer)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_INTEGER64.txt b/internal/help/_INTEGER64.txt index 351ffc283..ceb3974f6 100644 --- a/internal/help/_INTEGER64.txt +++ b/internal/help/_INTEGER64.txt @@ -1,17 +1,17 @@ {{DISPLAYTITLE:_INTEGER64}} -'''_INTEGER64''' is an 8 byte number type definition that can hold whole numerical values using '''QB64''' only. +[[_INTEGER64]] is an 8 byte number type definition that can hold whole numerical values. {{PageSyntax}} -: DIM {{Parameter|variable}} {{KW|AS}} [[_INTEGER64]] +: [[DIM]] {{Parameter|variable}} [[AS]] [[_INTEGER64]] {{PageDescription}} -* Can be used in '''QB64 only''' with 32 or 64 bit computers. +* Can be used in 32 or 64 bit computers. * Signed numerical values can range from -9223372036854775808 to 9223372036854775807. -* '''QB64''' {{KW|_UNSIGNED}} {{KW|_INTEGER64}} values range from 0 to 18446744073709551615 on 64 bit computers. +* [[_UNSIGNED]] [[_INTEGER64]] values range from 0 to 18446744073709551615 on 64 bit computers. * Variable type suffix is '''&&''' or '''~&&''' for [[_UNSIGNED]]. Suffix can also be placed after a literal or hexadecimal numerical value. -* Values can be converted to 8 byte [[ASCII]] character strings using [[_MK$]] and back using [[_CV]] in QB64. +* Values can be converted to 8 byte [[ASCII]] character strings using [[_MK$]] and back using [[_CV]]. * Equivalent to INT8 or unsigned as UINT8 in C programming. * '''When a variable has not been assigned or has no type suffix, the value defaults to [[SINGLE]].''' @@ -21,7 +21,7 @@ * [[_DEFINE]], [[DIM]] * [[_UNSIGNED]] * [[_CV]], [[_MK$]] -* [[PDS(7.1) Procedures#CURRENCY|CURRENCY]] +* [[PDS (7.1) Procedures#CURRENCY|CURRENCY]] * [[Variable Types]] diff --git a/internal/help/_KEYCLEAR.txt b/internal/help/_KEYCLEAR.txt index 5605fa292..42c14d630 100644 --- a/internal/help/_KEYCLEAR.txt +++ b/internal/help/_KEYCLEAR.txt @@ -1,25 +1,21 @@ -Briefly: Clear keyboard input buffers. - -{{PageSyntax}}_KEYCLEAR [buffer&] - -Buffer& indicates the buffer to be cleared: -* 1 - Clear the regular keyboard buffer, as used by all input command except the following: _KEYHIT, _KEYDOWN, INP(&H60. This is the same as the the emulated BIOS keyboard buffer, so legacy code reading from it via PEEK/POKE/CALL ABSOLUTE will also be affected. -* 2 - Clear the buffer used by _KEYHIT. -* 3 - Clear INP(&H60) buffer (but see the "Warning" section below). -* No parameter - Clear all three buffers. - - -Description: {{DISPLAYTITLE:_KEYCLEAR}} +[[_KEYCLEAR]] clears all keyboard input buffers. -The '''_KEYCLEAR''' command clears the specified keyboard input buffer. In effect, -it is as if a loop has been used to read from the buffer until it is empty. -All keys cleared are lost. +{{PageSyntax}} +:[[_KEYCLEAR]] {{Parameter|buffer&}} -This command is best used just before getting input, in order to clear stray -keypresses from commands such as SLEEP, or just random keyboard bashing by the -user. The programmer also aught to be weary of key release events in the -_KEYHIT buffer; consider the following code: +{{Parameters}} +*{{Parameter|buffer&}} indicates the buffer to be cleared: +** 1 - Clear the regular keyboard buffer, as used by all input command except the following: _KEYHIT, _KEYDOWN, INP(&H60. This is the same as the the emulated BIOS keyboard buffer, so legacy code reading from it via PEEK/POKE/CALL ABSOLUTE will also be affected. +** 2 - Clear the buffer used by _KEYHIT. +** 3 - Clear INP(&H60) buffer. (see '''Warning''' in the the description below) +* If no parameter is passed, all three buffers are cleared. + + +{{PageDescription}} +* The '''_KEYCLEAR''' command clears the specified keyboard input buffer. In effect, it is as if a loop has been used to read from the buffer until it is empty. All keys cleared are lost. +* '''Warning:''' The buffer read by INP(&H60) does not behave as the other buffers do. Whilst reading from the others will eventually empty after reading all data, this buffer will continue to return the last value. For this reason, [[_KEYCLEAR]] is of little effect, but is included for completeness (an internal flag indicating new data on the port is cleared). However, using [[INP]] for anything is strongly discouraged, and is for backwards compatibility only. +* This command is best used just before getting input, in order to clear stray key presses from commands such as SLEEP, or just random keyboard bashing by the user. The programmer also ought to be aware of key release events in the _KEYHIT buffer; consider the following code: {{CodeStart}} INPUT "Name: ", name$ @@ -28,13 +24,8 @@ _DELAY 2 'Simulate doing some processing that takes some time. PRINT _KEYHIT {{CodeEnd}} -The INPUT statement finishes as soon as the Enter key is struck; the program then -proceeds to clear all input buffers. Because this is executed so quickly, it is -likely that the user will release the Enter key after the _KEYCLEAR command is -executed, leaving a -13 (Enter key release) event in the _KEYHIT buffer. - -As mentioned above, it is best to place the _KEYCLEAR after the processing, -immediately before the PRINT _KEYHIT command: +* The INPUT statement finishes as soon as the Enter key is struck; the program then proceeds to clear all input buffers. Because this is executed so quickly, it is likely that the user will release the Enter key after the _KEYCLEAR command is executed, leaving a -13 (Enter key release) event in the _KEYHIT buffer. +* As mentioned above, it is best to place the _KEYCLEAR after the processing, immediately before the PRINT _KEYHIT command: {{CodeStart}} INPUT "Name: ", name$ @@ -44,6 +35,7 @@ PRINT _KEYHIT {{CodeEnd}} +{{PageExamples}} Example: {{CodeStart}} PRINT "Press a key" @@ -56,9 +48,10 @@ PRINT "In regular buffer, there is "; INKEY$ 'read regular buffer PRINT "In _KEYHIT buffer, there is "; _KEYHIT 'read the _KEYHIT buffer {{CodeEnd}} -Warning: -The buffer read by INP(&H60) does not behave as the other buffers do. Whilst reading from -the others will eventually empty after reading all data, this buffer will continue to return -the last value. For this reason, _KEYCLEAR is of little effect, but is included for completeness -(an internal flag indicating new data on the port is cleared). However, using INP for anything -is strongly discouraged, and is for backwards compatibility only. \ No newline at end of file + +{{PageSeeAlso}} +* [[SLEEP]] +* [[INKEY$]], [[_KEYHIT]] + + +{{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_KEYHIT.txt b/internal/help/_KEYHIT.txt index d918f1c94..11314cf0c 100644 --- a/internal/help/_KEYHIT.txt +++ b/internal/help/_KEYHIT.txt @@ -1,11 +1,13 @@ {{DISPLAYTITLE:_KEYHIT}} -The '''_KEYHIT''' function returns [[ASCII]] one and two byte, SDL Virtual Key and Unicode keyboard key press codes. +The [[_KEYHIT]] function returns [[ASCII]] one and two byte, OpenGL Virtual Key and Unicode keyboard key press codes. -{{PageSyntax}} keycode& = '''_KEYHIT''' +{{PageSyntax}} +:{{Parameter|keycode&}} = [[_KEYHIT]] -* Return values range up to &H40000000 so use a [[LONG]] or [[_INTEGER64]] variable type! See the [[_KEYDOWN]] code list: +{{PageDescription}} +* Return values range up to &H40000000 so use a [[LONG]] or [[_INTEGER64]] variable type. See the [[_KEYDOWN]] code list: :* 0-255: [[ASCII]] values (Refer to [http://en.wikipedia.org/wiki/Code_page_437 CP437]). :* 256-65535: [[ASCII#Two_Byte_Codes|2-byte]] character codes : code = [[CVI]]([[CHR$]](0) + [[CHR$]](scancode)) (unaffected by SHIFT/ALT/CTRL modifiers). :* 65536-&H40000000: [[_KEYDOWN|QB64-specific Virtual Key codes]] (designated with + for 100000 on keyboard below) @@ -38,14 +40,15 @@ The '''_KEYHIT''' function returns [[ASCII]] one and two byte, SDL Virtual Key a :* >= &H40000000: [[Unicode]]. -* Font '''cyberbit.ttf''', included with QB64 as of '''V0.92'''(October 2010), is required to facilitate the '''IME'''(in Chinese settings) only. The 12.7 MB font is free for '''non-commercial''' use and is not loaded unless the user switches to the '''Input Mode Editor'''. Set to "UNICODE". +* Font '''cyberbit.ttf''', included with QB64 ('''version 0.92 and up'''), is required to facilitate the '''IME'''(in Chinese settings) only. The 12.7 MB font is free for '''non-commercial''' use and is not loaded unless the user switches to the '''Input Mode Editor'''. Set to "UNICODE". <center>'''[http://www.fileformat.info/tip/microsoft/enter_unicode.htm Setting up the Unicode Input Method Editor in Windows]'''</center> <center>If you need help with IME support in '''Vista''' see the following article: [http://blogs.msdn.com/b/michkap/archive/2006/07/20/671835.aspx Setting up IME in Vista]</center> * QB64 can use several Windows fonts when '''cyberbit''' is not present so it is not necessary to include with program packages. * An '''important difference''' between [[INKEY$]] and _KEYHIT is how they work when '''CTRL, ALT''' or '''SHIFT''' are used. INKEY$ returns a different code if you hold down CTRL, ALT or SHIFT before pressing F1 (for example). _KEYHIT will return the same code regardless of which modifiers were used but you can check [[_KEYDOWN]] to see which modifying keys are being used. -* '''Keyboards with an Alt Gr key note:''' _KEYHIT may return both Alt(100307) and Ctrl(100306) codes when AltGr key is pressed or released. +* '''Keyboards with an Alt Gr key note:''' _KEYHIT may return both Alt (100307) and Ctrl (100306) codes when AltGr key is pressed or released. +{{PageExamples}} ''Example:'' This routine will return the codes for any keyboard presses. {{CodeStart}} '' '' @@ -99,15 +102,10 @@ unifont = {{Cl|_LOADFONT}}("cyberbit.ttf", 24, "UNICODE") {{small|Code by Galleon}} -<center>'''Find any keys that you cannot read or type in the IDE? Please report them at the forum link below:''' +<center>'''Find any keys that you cannot read or type in the IDE? Please report them at this forum link:''' http://www.qb64.net/forum/index.php?topic=1512.0</center> -http://www.qb64.net/forum/index.php?topic=1512.0</center> - - - - -''See also: +{{PageSeeAlso}} * [[_KEYDOWN]] {{text|(virtual key codes)}} * [[_MAPUNICODE]], [[_MAPUNICODE (function)]] * [[INKEY$]], [[ASCII]] {{text|(code table)}}, diff --git a/internal/help/_LASTAXIS.txt b/internal/help/_LASTAXIS.txt index cd8206d3d..a435694d9 100644 --- a/internal/help/_LASTAXIS.txt +++ b/internal/help/_LASTAXIS.txt @@ -1,18 +1,20 @@ {{DISPLAYTITLE:_LASTAXIS}} -The '''_LASTAXIS''' function returns the number of axis a specified number INPUT device on your computer has. +The [[_LASTAXIS]] function returns the number of axis a specified number INPUT device on your computer has. {{PageSyntax}} -::: axis_count% = '''_LASTAXIS('''''device_number''''')''' +: {{Parameter|axisCount%}} = [[_LASTAXIS]]({{Parameter|deviceNumber}}) +{{PageDescription}} * Returns the number of axis that can be read on a specified device number within the number of [[_DEVICES]] found. * A valid number can be sent to the [[_AXIS]] function to find any relative axis movements. * The devices are listed in a numerical order determined by the OS and can be read by the [[DEVICE$]] function. -* '''The [[_DEVICES]] function must be read BEFORE using _LASTAXIS or an [[ERROR Codes|"Illegal Function Call" error]] will occur!''' +* '''The [[_DEVICES]] function must be read before using _LASTAXIS or an [[ERROR Codes|"Illegal Function Call" error]] will occur.''' * Devices include keyboard(1), mouse(2), joysticks, game pads and multiple stick game controllers. +{{PageExamples}} ''Example:'' Checking for the system's input devices and number of axis. {{CodeStart}} '' '' devices = {{Cl|_DEVICES}} 'MUST be read in order for other 2 device functions to work! @@ -30,7 +32,7 @@ Axis: 2 :Note: The [[STRIG]]/[[STICK]] commands won't read from the keyboard or mouse device the above example lists. -''See also:'' +{{PageSeeAlso}} * [[_LASTBUTTON]], [[_LASTWHEEL]] * [[_AXIS]], [[_BUTTON]], [[_WHEEL]] * [[_DEVICE$]], [[_DEVICES]] diff --git a/internal/help/_LASTBUTTON.txt b/internal/help/_LASTBUTTON.txt index 1f43dfe28..d046516a2 100644 --- a/internal/help/_LASTBUTTON.txt +++ b/internal/help/_LASTBUTTON.txt @@ -1,19 +1,20 @@ {{DISPLAYTITLE:_LASTBUTTON}} -The '''_LASTBUTTON''' function returns the number of buttons a specified number INPUT device on your computer has. +The [[_LASTBUTTON]] function returns the number of buttons a specified INPUT device on your computer has. {{PageSyntax}} -::: button_count% = _LASTBUTTON(''device_number'') +: {{Parameter|buttonCount%}} = _[[_LASTBUTTON]]({{Parameter|deviceNumber}}) * Returns the number of buttons that can be read on a specified device number within the number of [[_DEVICES]] found. * A valid number can be sent to the [[_BUTTON]] or [[_BUTTONCHANGE]] function to find any button events. -* The specific device name and functions can be found by the [[_DEVICE$]] function [[STRING]]. +* The specific device name and functions can be found by the [[_DEVICE$]] function [[STRING|string]]. * The devices are listed in a numerical order determined by the OS and can be read by the [[DEVICE$]] function. -* '''The [[_DEVICES]] function must be read BEFORE using _LASTBUTTON or an [[ERROR Codes|"Illegal Function Call" error]] will occur!''' -* Devices include keyboard(1), mouse(2), joysticks, game pads and multiple stick game controllers. +* '''The [[_DEVICES]] function must be read before using _LASTBUTTON or an [[ERROR Codes|"Illegal Function Call" error]] will occur.''' +* Devices include keyboard (reported as 1), mouse (reported as 2), joysticks, game pads and multiple stick game controllers. +{{PageExamples}} ''Example:'' Checking for the system's input devices. {{CodeStart}} '' '' devices = {{Cl|_DEVICES}} 'MUST be read in order for other 2 device functions to work! @@ -32,7 +33,7 @@ Buttons: 3 :Note: The [[STRIG]]/[[STICK]] commands won't read from the keyboard or mouse device the above example lists. -''See also:'' +{{PageSeeAlso}} * [[_LASTAXIS]], [[_LASTWHEEL]] * [[_AXIS]], [[_BUTTON]], [[_WHEEL]] * [[_DEVICES]], [[_DEVICE$]] diff --git a/internal/help/_LASTWHEEL.txt b/internal/help/_LASTWHEEL.txt index 54a2b891d..c92774504 100644 --- a/internal/help/_LASTWHEEL.txt +++ b/internal/help/_LASTWHEEL.txt @@ -1,18 +1,19 @@ {{DISPLAYTITLE:_LASTWHEEL}} -The '''_LASTWHEEL''' function returns the number of wheels a specified number INPUT device on your computer has. +The [[_LASTWHEEL]] function returns the number of wheels a specified number INPUT device on your computer has. {{PageSyntax}} -::: wheel_count% = '''_LASTWHEEL('''''device_number''''')''' +: {{Parameter|wheelCount%}} = [[_LASTWHEEL]]({{Parameter|deviceNumber}}) * Returns the number of wheels that can be used on a specified device number within the number of [[_DEVICES]] found. * A valid number can be sent to the [[_WHEEL]] function to find any relative positive or negative wheel movements. -* The devices are listed in a numerical order determined by the OS and can be read by the [[DEVICE$]] function. -* '''The [[_DEVICES]] function must be read BEFORE using _LASTWHEEL or an [[ERROR Codes|"Illegal Function Call" error]] may occur!''' -* Devices include keyboard(1), mouse(2), joysticks, game pads and multiple stick game controllers. +* The devices are listed in a numerical order determined by the OS and can be read by the [[_DEVICE$]] function. +* '''The [[_DEVICES]] function must be read before using _LASTWHEEL or an [[ERROR Codes|"Illegal Function Call" error]] may occur.''' +* Devices include keyboard (reported as 1), mouse (reported as 2), joysticks, game pads and multiple stick game controllers. +{{PageExamples}} ''Example:'' Checking for the system's input devices and number of wheels available. {{CodeStart}} '' '' devices = {{Cl|_DEVICES}} 'MUST be read in order for other 2 device functions to work! @@ -30,7 +31,7 @@ Wheels: 3 : ''Note:'' A mouse may have 3 wheels listed when there is only one scroll wheel. -''See also:'' +{{PageSeeAlso}} * [[_LASTBUTTON]], [[_LASTAXIS]] * [[_AXIS]], [[_BUTTON]], [[_WHEEL]] * [[_DEVICE$]], [[_DEVICES]] diff --git a/internal/help/_LIMIT.txt b/internal/help/_LIMIT.txt index 14afd6211..608612aa0 100644 --- a/internal/help/_LIMIT.txt +++ b/internal/help/_LIMIT.txt @@ -1,20 +1,21 @@ {{DISPLAYTITLE:_LIMIT}} -The '''_LIMIT''' statement sets the loop repeat rate of a program to so many per second, relinquishing spare cpu cycles to other applications. +The [[_LIMIT]] statement sets the loop repeat rate of a program to so many per second, relinquishing spare CPU cycles to other applications. {{PageSyntax}} -::: [[_LIMIT]] ({{Parameter|LoopsPerSecond!}}) +: [[_LIMIT]] ({{Parameter|framesPerSecond!}}) -* The frames per second [[SINGLE]] parameter value adjusts the loops per second of a program loop. '''Do not use negative values!''' -* The loop code is executed before the loop is delayed. Loop cycles below once per second may delay program [[_EXIT]]s! +* The {{Parameter|framesPerSecond!}} [[SINGLE]] parameter value adjusts the loops per second of a program loop. '''Do not use negative values.''' +* The loop code is executed before the loop is delayed. Loop cycles below once per second may delay program [[_EXIT]]s. * _LIMIT measures its interval from the previous time that it was called and minor adjustments are automatically made to ensure that the number of times a loop is repeated is correct overall. -* Loop cycle rates of 1000 or less can '''significantly reduce CPU useage''' in programs! -* Do NOT use it to limit a loop to '''less than once every 60 seconds'''(.0167) or an [[ERROR Codes|ILLEGAL FUNCTION CALL error]] will occur. +* Loop cycle rates of 1000 or less can '''significantly reduce CPU usage''' in programs. +* Do not use it to limit a loop to '''less than once every 60 seconds'''(.0167) or an [[ERROR Codes|ILLEGAL FUNCTION CALL error]] will occur. * Do not use _LIMIT as a timing delay outside of loops. Use [[_DELAY]] instead. * Use _LIMIT to slow down old Qbasic program loops that run too fast and use too much CPU. +{{PageExamples}} ''Example:'' Limits loop execution to 30 frames per second and limits the program's CPU usage. {{CodeStart}} '' '' {{Cl|PRINT}} "To Quit press ESC key!" diff --git a/internal/help/_LOADFONT.txt b/internal/help/_LOADFONT.txt index 4706fb589..903b39408 100644 --- a/internal/help/_LOADFONT.txt +++ b/internal/help/_LOADFONT.txt @@ -1,25 +1,28 @@ {{DISPLAYTITLE:_LOADFONT}} -The '''_LOADFONT''' function loads a TrueType font (.TTF) file of a specific size and style and returns a [[LONG]] font handle value > 0. +The [[_LOADFONT]] function loads a TrueType font (.TTF) or an OpenType font (.OTF) file in a specific size and style and returns a [[LONG]] font handle. {{PageSyntax}} -: handle& = '''_LOADFONT ('''''TTF_filename$'', ''size%''[, "{MONOSPACE|, BOLD|, ITALIC|, UNDERLINE|, UNICODE|, DONTBLEND}"]''')''' +: {{Parameter|handle&}} = [[_LOADFONT]]({{Parameter|fontFileName$}}, {{Parameter|size%}}[, "{MONOSPACE|, BOLD|, ITALIC|, UNDERLINE|, UNICODE|, DONTBLEND}"]) {{PageDescription}} -* The assigned [[LONG]] font ''handle'' variable return value designates a font style to be used somewhere in a program. -* ''TTF_filename$'' is the filename of '''truetype''' fonts only. Can include the path to the font file. Best to include font files with a program. -* ''Size'' is the [[INTEGER]] height of the font. If the size is too large or small an [[ERROR Codes|error]] will occur! -* Optional comma separated ''style'' parameter(s) used are literal [[STRING]]s(in quotes) or can be contained in variable(s). -:* '''"MONOSPACE" has limited font file selections and cannot be used with variable width fonts!''' -:* '''"BOLD", "ITALIC"''' or '''"UNDERLINE"''' create bold, italic or underlined fonts when available in font. -:* '''"UNICODE"''' loads Unicode fonts such as ''cyberbit.ttf'' which is included in the QB64 downloads. -:* '''"DONTBLEND"''' turns off [[_ALPHA]] blending of fonts. This can also be done with the [[_DONTBLEND]] statement. -:* You can pass different font styles using different predefined [[STRING]] variable lists. You '''can''' include an empty style string! -* '''Always check that font handle values are greater than 0 before using them or [[ERROR Codes|illegal function errors]] may occur!''' -* '''NOTE: SCREEN 0 can only use ONE font on a screen page! Thus a style like underline would affect the entire page.''' -* Font sizes can be found using the [[_FONTHEIGHT]] function. Font ''size''s can also affect [[SCREEN (statement)|SCREEN]] sizes! -* [[_FONTWIDTH]] can only measure MONOSPACE fonts! '''"MONOSPACE" cannot be used on a variable width font.''' +* The assigned [[LONG]] font {{Parameter|handle&}} variable return value designates a font style to be used somewhere in a program. Valid handle values are greater than 0 ('''{{Parameter|handle&}} > 0'''). +* {{Parameter|fontFileName$}} is the filename of a TrueType or OpenType font. Can include the path to the font file. Best practice is to include font files with a program. +* If no path is specified for {{Parameter|fontFileName$}} and the font file isn't in the same folder as the resulting binary, QB64 attempts to load from the default ''C:\Windows\Fonts'' path. +* {{Parameter|size%}} is the [[INTEGER]] height of the font. If the size is too large or small an [[ERROR Codes|error]] will occur. +* Optional comma separated ''style'' parameter(s) used are literal [[STRING]]s (in quotes) or can be contained in variable(s). +** '''"MONOSPACE"''' loads a font with all characters occupying the same width. Results may be too spaced out for fonts that aren't designed for monospace use. +** '''"BOLD", "ITALIC"''' or '''"UNDERLINE"''' create bold, italic or underlined fonts when available in font. +***(valid for QB64 versions prior to 1.000). +***For '''QB64 1.000 or later''', you must specify the proper file name according to the desired attributes. For example, Courier New is in font '''cour.ttf''' while Courier New Bold is in font '''courbd.ttf''', as shipped with Windows. +** '''"UNICODE"''' loads Unicode fonts such as ''cyberbit.ttf'' which is included in the QB64 downloads. +** '''"DONTBLEND"''' turns off [[_ALPHA]] blending of fonts. This can also be done with the [[_DONTBLEND]] statement. +:* You can pass different font styles using different predefined [[STRING]] variable lists. You '''can''' include an empty style string. +* '''Always check that font handle values are greater than 0 ('''{{Parameter|handle&}} > 0''') before using them or [[ERROR Codes|illegal function errors]] may occur.''' +* '''NOTE: SCREEN 0 can only use ONE font on a screen page. Thus a style like underline would affect the entire page.''' +* Font sizes can be found using the [[_FONTHEIGHT]] function. Font ''size''s can also affect [[SCREEN (statement)|SCREEN]] sizes. +* [[_FONTWIDTH]] can only measure monospaced fonts. '''"MONOSPACE" can be used to load a variable width font as a monospace font.''' * [[_PRINTWIDTH]] can measure the width of a string of text in '''graphics modes only'''. Use one character to get the font's width. @@ -29,24 +32,24 @@ The '''_LOADFONT''' function loads a TrueType font (.TTF) file of a specific siz * '''Predefined QB64''' font handle numbers can be substituted before freeing a font handle: **'''_FONT 8 ''' - default font for [[SCREEN (statement)|SCREEN]] 1, 2, 7, 8 or 13 **'''_FONT 14''' - default font for [[SCREEN (statement)|SCREEN]] 9 or 10 -**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ({{KW|WIDTH}} 80, 25 text only), 11 or 12 +**'''_FONT 16''' - default font for [[SCREEN (statement)|SCREEN]] 0 ([[WIDTH]] 80, 25 text only), 11 or 12 **'''_FONT 9, 15''' and '''17''' are the double width versions of 8, 14 and 16 respectively in text '''SCREEN 0 only'''. * Once the font is changed to a predefined value, the font handle value can be freed using [[_FREEFONT]] for another font type. -* Font handle values of -1 (load failure) '''do not''' need to be freed! '''An [[ERROR Codes|error]] will occur if you try to free invalid handles!''' +* Font handle values of -1 (load failure) '''do not''' need to be freed. '''An [[ERROR Codes|error]] will occur if you try to free invalid handles.''' <center> '''Font File Specs'''</center> * Windows users should find '''TTF''' font files in the C:\WINDOWS\FONTS folder, but don't depend on unusual ones being there. -* '''Check the font file name! The name in the "viewer" is NOT necessarily the file's name! Use the name in properties!''' +* '''Check the font file name. The name in the "viewer" is not necessarily the file's name. Use the name in properties (right click a font listed and choose Properties in the contextual menu)''' * If a program is on a different drive than Windows, [[ENVIRON$]]("SYSTEMROOT") will return the path to the "WINDOWS" folder. Normally "C:\WINDOWS". Then add the "\FONTS\" folder and the font '''.TTF''' filename to the path [[STRING]]. +{{PageExamples}} ''Example 1:'' You need to know that if you are in a text mode (such as SCREEN 0 - the default) then you will only be able to use mono-spaced (fixed width) fonts. - {{CodeStart}} rootpath$ = {{Cl|ENVIRON$}}("SYSTEMROOT") 'normally "C:\WINDOWS" fontfile$ = rootpath$ + "\Fonts\cour.ttf" 'TTF file in Windows -style$ = "monospace, italic, bold" 'font style is not case sensitive +style$ = "monospace" 'font style is not case sensitive f& ={{Cl|_LOADFONT}}(fontfile$, 30, style$) {{Cl|_FONT}} f& {{Cl|PRINT}} "Hello!" @@ -54,7 +57,7 @@ f& ={{Cl|_LOADFONT}}(fontfile$, 30, style$) {{CodeEnd}} {{OutputStart}} -'''''Hello!''''' +Hello! {{OutputEnd}} @@ -120,7 +123,7 @@ QuickUTF16toUTF32$ = b$ {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_FONT]], [[_FONT (function)]] * [[_FREEFONT]] * [[_PRINTSTRING]], [[_PRINTWIDTH]] diff --git a/internal/help/_LOADIMAGE.txt b/internal/help/_LOADIMAGE.txt index 6a21cd6a0..04810a2aa 100644 --- a/internal/help/_LOADIMAGE.txt +++ b/internal/help/_LOADIMAGE.txt @@ -1,34 +1,37 @@ {{DISPLAYTITLE:_LOADIMAGE}} -The '''_LOADIMAGE''' function loads an image into memory and returns valid [[LONG]] image handle values that are less than -1. +The [[_LOADIMAGE]] function loads an image into memory and returns valid [[LONG]] image handle values that are less than -1. {{PageSyntax}} -:: handle& = '''_LOADIMAGE& ('''''filename$''[, ''mode&'']''')''' +: {{Parameter|handle&}} = [[_LOADIMAGE]]({{Parameter|filename$}}[, {{Parameter|mode%}}]) {{Parameters}} -* ''filename'' is literal or variable [[STRING]] file name value. -* Optional ''mode'' [[INTEGER]] values can be any valid screen mode except zero, 256 color, 32 bit or 33 hardware image. +* {{Parameter|filename$}} is literal or variable [[STRING]] file name value. +* Optional {{Parameter|mode%}} [[INTEGER]] values can be '''any valid [[SCREEN|screen]] mode''' except zero, also: +** 256 = 8-bit (256-color) +** 32 = 32-bit +** 33 = hardware image {{PageDescription}} * File types supported: BMP, JPG, PNG, GIF, PNM, XPM, XCF, PCX, TIF, LBM, and TGA. A path can also be given. -* The ''mode&'' can designate 256(8 bit), 32 bit color or 33 in GL. Omit to use the current graphic screen settings. -* '''QB64GL''' mode 33 images are '''hardware''' accelerated and are created using [[_LOADIMAGE]] or [[_COPYIMAGE]] ([[_NEWIMAGE]] will later) +* The {{Parameter|mode%}} can designate 256 (8 bit), 32 bit color or 33 ('''version 1.000 and up'''). Omit to use the current graphic screen settings. +* Mode 33 images are '''hardware''' accelerated and are created using [[_LOADIMAGE]] or [[_COPYIMAGE]] ('''version 1.000 and up'''). * Loaded images can be read invisibly using [[POINT]]. Image coordinates start at 0 up to the [[_WIDTH (function)|_WIDTH]] - 1 and [[_HEIGHT]] - 1. * Images can be made into a program [[SCREEN (statement)|SCREEN]] or page adopting the size and palette settings or placed using [[_PUTIMAGE]]. -* Returns -1 as an invalid handle if it could not load the image. Valid {{KW|LONG}} handle returns are less than -1. -* Valid images only need to be loaded ONCE! The handle can be used repeatedly until freed. +* Returns -1 as an invalid handle if it can't load the image. Valid [[LONG]] handle returns are less than -1 ({{Parameter|handle&}} < -1). +* Valid images only need to be loaded once. The handle can be used repeatedly until freed. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' {{PageErrors}} -* Some picture file images may not load when a ''mode'' value is designated. Try loading it without a ''mode'' designation. -* '''It is IMPORTANT to free unused or discarded images with [[_FREEIMAGE]] to prevent CPU memory overflow errors!''' -* '''In text [[SCREEN]] 0 ''mode&'' 32 must be designated!''' When loading an [[_ICON]] image use 32 for the mode also. -* '''QB64 SDL does not support icon files! A bad handle value will occur using _LOADIMAGE! See [[_ICON]] example 2.''' +* Some picture file images may not load when a {{Parameter|mode%}} value is designated. Try loading it without a {{Parameter|mode%}} designation. +* '''It is important to free unused or discarded images with [[_FREEIMAGE]] to prevent CPU memory overflow errors.''' +* '''In text-only [[SCREEN]] 0, {{Parameter|mode%}} 32 must be specified.''' When loading an [[_ICON]] image use 32 for the {{Parameter|mode%}} too. +{{PageExamples}} ''Example 1:'' Already in SCREEN 13 and want computer to match the 32-bit jpg/etc. colors to the current palette: {{CodeStart}} '' '' @@ -83,16 +86,14 @@ DO :''NOTE:'' The ''QB64.PNG'' file picturing the QB64 bee can saved from the top of the [http://www.qb64.net/forum/index.php QB64 forum]. Speed varies with image size. -''See Examples:'' +===More examples=== * [[SAVEIMAGE]] (QB64 Image to Bitmap SUB by Galleon) - -* [[Program ScreenShots]] (Member program for legacy screen modes) - +* [[Program ScreenShots]] (Member-contributed program for legacy screen modes) * [[ThirtyTwoBit SUB]] (QB64 Image area to bitmap) {{PageSeeAlso}} -* [[_FREEIMAGE]], [[_ICON]] {{text|(Icons can be used in GL only!)}} +* [[_FREEIMAGE]], [[_ICON]] * [[_PUTIMAGE]], [[_MAPTRIANGLE]] * [[_NEWIMAGE]], [[_COPYIMAGE]] * [[_PRINTIMAGE]] (printer) diff --git a/internal/help/_MAPTRIANGLE.txt b/internal/help/_MAPTRIANGLE.txt index 8f6e0a2a0..18773fa60 100644 --- a/internal/help/_MAPTRIANGLE.txt +++ b/internal/help/_MAPTRIANGLE.txt @@ -1,42 +1,43 @@ {{DISPLAYTITLE:_MAPTRIANGLE}} -The '''_MAPTRIANGLE''' statement maps a triangular portion of an image onto a destination image or screen page. +The [[_MAPTRIANGLE]] statement maps a triangular portion of an image onto a destination image or screen page. -{{PageSyntax}} 2D drawing - -'''_MAPTRIANGLE''' [{_SEAMLESS}] '''('''''sx1''''',''' ''sy1''''')-('''''sx2''''',''' ''sy2''''')-('''''sx3''''',''' ''sy3'''''),''' ''source&'' '''TO ('''''dx1''''',''' ''dy1''''')-('''''dx2''''',''' ''dy2''''')-('''''dx3''''',''' ''dy3''''')'''[, ''destination&''][{_SMOOTH|_SMOOTHSHRUNK|_SMOOTHSTRETCHED}]] +{{PageSyntax}} +===2D drawing=== +:[[_MAPTRIANGLE]] [{_SEAMLESS}] '''('''{{Parameter|sx1}}''',''' {{Parameter|sy1}}''')-('''{{Parameter|sx2}}''',''' {{Parameter|sy2}}''')-('''{{Parameter|sx3}}''',''' {{Parameter|sy3}}'''),''' {{Parameter|source&}} '''TO ('''{{Parameter|dx1}}''',''' {{Parameter|dy1}}''')-('''{{Parameter|dx2}}''',''' {{Parameter|dy2}}''')-('''{{Parameter|dx3}}''',''' {{Parameter|dy3}}''')'''[, {{Parameter|destination&}}][{_SMOOTH|_SMOOTHSHRUNK|_SMOOTHSTRETCHED}]] -{{PageSyntax}} 3D drawing (hardware images only) +===3D drawing (hardware images only)=== -'''_MAPTRIANGLE''' [{_CLOCKWISE|_ANTICLOCKWISE}] [{_SEAMLESS}] '''('''''sx1''''',''' ''sy1''''')-('''''sx2''''',''' ''sy2''''')-('''''sx3''''',''' ''sy3'''''),''' ''source&'' '''TO ('''''dx1''''',''' ''dy1''''',''' ''dz1''''')-('''''dx2''''',''' ''dy2''''',''' ''dz2''''')-('''''dx3''''',''' ''dy3''''',''' ''dz3''''')'''[, ''destination&''][{_SMOOTH|_SMOOTHSHRUNK|_SMOOTHSTRETCHED}]] +:[[_MAPTRIANGLE]] [{_CLOCKWISE|_ANTICLOCKWISE}] [{_SEAMLESS}] '''('''{{Parameter|sx1}}''',''' {{Parameter|sy1}}''')-('''{{Parameter|sx2}}''',''' {{Parameter|sy2}}''')-('''{{Parameter|sx3}}''',''' {{Parameter|sy3}}'''),''' {{Parameter|source&}} '''TO ('''{{Parameter|dx1}}''',''' {{Parameter|dy1}}''',''' {{Parameter|dz1}}''')-('''{{Parameter|dx2}}''',''' {{Parameter|dy2}}''',''' {{Parameter|dz2}}''')-('''{{Parameter|dx3}}''',''' {{Parameter|dy3}}''',''' {{Parameter|dz3}}''')'''[, {{Parameter|destination&}}][{_SMOOTH|_SMOOTHSHRUNK|_SMOOTHSTRETCHED}]] {{Parameters}} -* The '''_SEAMLESS''' option makes the triangle skip the right-most and bottom-most pixels of the triangle. When you make larger objects using several triangles, there can be a "seam" where they overlap when using alpha transparency and the seam would be twice as bright! '''_SEAMLESS''' is ignored when rendering 3D content and is not yet supported when drawing 2D hardware images.''' +* The '''_SEAMLESS''' option makes the triangle skip the right-most and bottom-most pixels of the triangle. When you make larger objects using several triangles, there can be a "seam" where they overlap when using alpha transparency and the seam would be twice as bright. '''_SEAMLESS''' is ignored when rendering 3D content and is not yet supported when drawing 2D hardware images.''' * For 3D drawing use the '''_CLOCKWISE''' and '''_ANTICLOCKWISE''' arguments to only draw triangles in the correct direction. See ''Example 4''. * Coordinates are [[SINGLE]] values where whole numbers represent the exact center of a pixel of the source texture. -* ''source'' and optional ''destination'' are [[LONG]] image or screen page handle values. -* Supports an optional final argument called '''_SMOOTH''' which applies linear filtering. See ''Example 3''. +* {{Parameter|source&}} and optional {{Parameter|destination&}} are [[LONG]] image or screen page handles. +* Supports an optional final argument '''_SMOOTH''' which applies linear filtering. See ''Example 3''. * Use '''_SMOOTHSTRETCHED''' or '''_SMOOTHSHRUNK''' for when a pixelated/smooth effect is desirable but not both. {{PageDescription}} * This statement is used similar to [[_PUTIMAGE]] to place triangular sections of an image, but is more flexible. * The [[STEP]] keyword can be used to for coordinates relative to the last graphic coordinates used. -* For 2D drawing, the destination coordinates are pixel co-ordinates either on-screen or on the destination image. -* For 3D drawing, the destination coordinates represent left(-x) to right(+x), bottom(-y) to top(+y) & furthest(-z) to nearest(z=-1). The center of the screen is therefore (0,0,-1). Note that a z value of 0 will not result in on-screen content. The furthest visible z value is -10,000. +* For 2D drawing, the destination coordinates are pixel coordinates either on-screen or on the destination image. +* For 3D drawing, the destination coordinates represent left (-x) to right (+x), bottom (-y) to top (+y) & furthest (-z) to nearest (z=-1). The center of the screen is therefore (0,0,-1). Note that a z value of 0 will result in off-screen content. The furthest visible z value is -10,000. * When drawing '''software images''' coordinate positions are '''limited from -16383 to 16383''' * The source coordinates can be positioned outside the boundary of the ''source'' image to achieve a tiled effect. -* If the ''destination'' image handle is the current [[SCREEN]] page, [[_DEST]] or hardware layer then it can be omitted. +* If the {{Parameter|destination&}} image handle is the current [[SCREEN]] page, [[_DEST]] or hardware layer, then it can be omitted. * '''Hardware images''' (created using mode 33 via [[_LOADIMAGE]] or [[_COPYIMAGE]]) can be used as the source or destination. -''Example 1:'' Rotating the [https://dl.dropboxusercontent.com/u/8440706/QB64bee.png QB64bee] image using a rotation and zoom SUB with _MAPTRIANGLE. +{{PageExamples}} +''Example 1:'' Rotating the [http://www.qb64.net/qb64_trans.png QB64 bee] image using a rotation and zoom SUB with _MAPTRIANGLE. {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 32) -Image& = {{Cl|_LOADIMAGE}}("Qb64bee.png") '<<< [http://www.qb64.net/forum/index.php Image from top of QB64 Forum] +Image& = {{Cl|_LOADIMAGE}}("qb64_trans.png") '<<< [http://www.qb64.net/qb64_trans.png Image from top of QB64 Forum] {{Cl|DO}} {{Cl|CLS}} @@ -71,7 +72,7 @@ sinr! = {{Cl|SIN}}(-Rotation / 57.2957795131): cosr! = {{Cl|COS}}(-Rotation / 57 {{WhiteEnd}} -''Example 2:'' A 3D Spinning Cube demo using the [https://dl.dropboxusercontent.com/u/8440706/QB64bee.png QB64bee] software image and [[_MAPTRIANGLE]]: +''Example 2:'' A 3D Spinning Cube demo using the [http://www.qb64.net/qb64_trans.png QB64 bee] software image and [[_MAPTRIANGLE]]: {{CodeStart}} '' '' ' Copyright (C) 2011 by Andrew L. Ayers @@ -150,7 +151,7 @@ PLANECOL(5) = 8 ' {{Cl|_TITLE}} "QB64 _MAPTRIANGLE CUBE DEMO" {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 32) -TextureImage& = {{Cl|_LOADIMAGE}}("qb64bee.png") ''''<<<< '''[http://www.qb64.net/forum/index.php Image from top of QB64 Forum] +TextureImage& = {{Cl|_LOADIMAGE}}("qb64_trans.png") ''''<<<< '''[http://www.qb64.net/qb64_trans.png Image from top of QB64 Forum] '{{Cl|_PUTIMAGE}} , Image& DO @@ -360,7 +361,7 @@ DO {{CodeEnd}}{{small|Demo by Andrew L. Ayers}} -''Example 3:'' A 3D Spinning Cube demo using the [https://dl.dropboxusercontent.com/u/8440706/QB64bee.png QB64bee] hardware image and '''QB64GL''' hardware acceleration with [[_MAPTRIANGLE]]: +''Example 3:'' A 3D Spinning Cube demo using the [http://www.qb64.net/qb64_trans.png QB64 bee] hardware image and '''QB64GL''' hardware acceleration with [[_MAPTRIANGLE]]: {{CodeStart}} '' '' ' Copyright (C) 2011 by Andrew L. Ayers @@ -440,7 +441,7 @@ PLANECOL(5) = 8 {{Cl|_TITLE}} "QB64 {{Cl|_MAPTRIANGLE}} CUBE DEMO" {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 32) -TextureImage& = {{Cl|_LOADIMAGE}}("qb64bee.png", 32)'<<<< Image from top of QB64 Forum http://www.qb64.net/forum/index.php +TextureImage& = {{Cl|_LOADIMAGE}}("qb64_trans.png", 32)'<<<< Image from top of QB64 Forum http://www.qb64.net/qb64_trans.png {{Cl|_SETALPHA}} 128, , TextureImage& TextureImage& = {{Cl|_COPYIMAGE}}(TextureImage&, 33)'copy of hardware image @@ -698,7 +699,7 @@ DO : '''Tip:''' If you are using Linux you might want to replace "[[_SCREENIMAGE]]" with a [[_LOADIMAGE]] command if you don't see anything. -''See also:'' +{{PageSeeAlso}} * [[_PUTIMAGE]] * [[_LOADIMAGE]] * [[_COPYIMAGE]] diff --git a/internal/help/_MAPUNICODE.txt b/internal/help/_MAPUNICODE.txt index ca602e863..1c8a41259 100644 --- a/internal/help/_MAPUNICODE.txt +++ b/internal/help/_MAPUNICODE.txt @@ -1,20 +1,21 @@ {{DISPLAYTITLE:_MAPUNICODE}} -The '''_MAPUNICODE''' statement maps a [[Unicode]] value to an [[ASCII]] character code value. +The [[_MAPUNICODE]] statement maps a [[Unicode]] value to an [[ASCII]] character code value. {{PageSyntax}} -:: '''_MAPUNICODE''' Unicode& '''TO''' ''ascii_code%'' +: [[_MAPUNICODE]] {{Parameter|unicode&}} '''TO''' {{Parameter|asciiCode%}} -* The [[LONG]] ''Unicode'' value is a [[HEX$|hexadecimal]] or decimal code value from a [[Unicode]] [[Code Pages|Code Page]]. -* The ''asciivalue%'' [[INTEGER]] parameter is any [[ASCII]] or Extended code value from 0 to 255. +* The [[LONG]] {{Parameter|unicode&}} value is a [[HEX$|hexadecimal]] or decimal code value from a [[Unicode]] [[Code Pages|Code Page]]. +* The {{Parameter|asciiCode%}} [[INTEGER]] parameter is any [[ASCII]] or Extended code value from 0 to 255. * Use the Unicode Page Table values listed here: [http://en.wikipedia.org/wiki/Category:DOS_code_pages DOS Code Pages] or [http://unicode.org/Public/MAPPINGS/VENDORS/MICSFT/WINDOWS/ Windows Mapping] * Once the codes are mapped, key entries will display the unicode character in the '''monospace ''' [[_FONT|font]] selected. * The [[_MAPUNICODE (function)|_MAPUNICODE]] function can be used to verify or read the present [[Unicode]] UTF32 code point settings. +* '''[[_MAPUNICODE]] can place the Unicode characters TO any [[ASCII]] code space you desire (0 to 255)'''. - +{{PageExamples}} ''Example:'' Converting the extended [[ASCII]] characters to other characters using DATA from the Unicode [[Code Pages]]. {{CodeStart}} '' '' {{Cl|SCREEN}} 0 @@ -48,12 +49,13 @@ Microsoft_pc_cpMIK: -''See also:'' +{{PageSeeAlso}} * [[_MAPUNICODE (function)]] * [[ASCII]], [[Unicode]], [[_FONT]] * [[_KEYHIT]], [[_KEYDOWN]] * [[ASC]], [[INKEY$]], [[CHR$]] -* [[Code Pages]] {{text|{by region)}} +* [[Code Pages]] {{text|(by region)}} +* [[Text Using Graphics]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MAPUNICODE_(function).txt b/internal/help/_MAPUNICODE_(function).txt index 3a1148dc1..fff6820f1 100644 --- a/internal/help/_MAPUNICODE_(function).txt +++ b/internal/help/_MAPUNICODE_(function).txt @@ -1,18 +1,19 @@ {{DISPLAYTITLE:_MAPUNICODE (function)}} -The '''_MAPUNICODE''' function returns the [[Unicode]](UTF32) code point value of a mapped [[ASCII]] character code. - +The [[_MAPUNICODE]] function returns the [[Unicode]] (UTF-32) code point value of a mapped [[ASCII]] character code. {{PageSyntax}} -:: UTFvalue& = '''_MAPUNICODE('''''Ascii_code%''''')''' +: {{Parameter|utfValue&}} = [[_MAPUNICODE]]({{Parameter|asciiCode%}}) -* The UTF32 values have 4 byte encoding so the return variable should be [[LONG]]. -* The ''Ascii_code'' can be any [[INTEGER]] value from 0 to 255. +{{PageDescription}} +* UTF-32 values have 4-byte encoding so the return variable should be [[LONG]]. +* The {{Parameter|asciiCode%}} can be any [[INTEGER]] value from 0 to 255. * Returns can be used to verify or catalog the present Unicode mapping. -* The function will return Unicode values for the control characters, CHR$(127) and extended characters '''without mapping''' them first. +* The function returns Unicode values for the control characters, CHR$(127) and extended characters without mapping them first. +{{PageExamples}} ''Example:'' Store function return values in an array for ASCII codes 0 to 255 to restore them later. {{CodeStart}} {{Cl|DIM}} Unicode&(255) @@ -28,10 +29,11 @@ Unicode&(ascii) = {{Cl|_MAPUNICODE (function)|_MAPUNICODE}}(ascii) 'read {{CodeEnd}} -''See also:'' -* [[_MAPUNICODE]] (statement) -* [[Unicode]], [[Code Pages]] (by region) +{{PageSeeAlso}} +* [[_MAPUNICODE]] {{text|(statement)}} +* [[Unicode]], [[Code Pages]] {{text|(by region)}} * [[ASCII]], [[CHR$]], [[ASC]] +* [[Text Using Graphics]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MEM.txt b/internal/help/_MEM.txt index 56cdbbb08..953d74f43 100644 --- a/internal/help/_MEM.txt +++ b/internal/help/_MEM.txt @@ -1,11 +1,12 @@ {{DISPLAYTITLE:_MEM}} -The '''_MEM''' variable type can be used when working with memory blocks. It has no variable [[type]] suffix. Effective version ''.954''. +The [[_MEM]] variable type can be used when working with memory blocks. It has no variable [[type]] suffix. {{PageSyntax}} -::: [[DIM]] m [[AS]] '''_MEM''' +: [[DIM]] m [[AS]] [[_MEM]] +{{PageDescription}} ''Variable TYPE:'' * Memory DOT values are actually part of the built in memory variable [[type]] in QB64. The following [[TYPE]] is built in: {{WhiteStart}}TYPE memory_type @@ -16,47 +17,49 @@ The '''_MEM''' variable type can be used when working with memory blocks. It has IMAGE AS LONG 'the image handle used when _MEMIMAGE(handle) is used END TYPE -{{text|The above [[TYPE]] is for clarification purposes only. It is not required to use _MEM!|red}} +{{text|The above [[TYPE]] is for clarification purposes only. It '''doesn't need''' to be pasted in a program to use _MEM.|red}} + +{{text|''IMPORTANT NOTE: As of Build 20170802/57 onward, mem.TYPE has been changed to be an _OFFSET, just as mem.SIZE and mem.ELEMENTSIZE.''|red}} {{WhiteEnd}} - -''Usage:'' -* The _MEM type contains the following '''read only''' DOT elements where ''name'' is the _MEM variable name: +===Usage=== +* The _MEM type contains the following '''read-only''' elements where ''name'' is the _MEM variable name: :: ''name'''''.OFFSET''' is the current start position in the memory block AS [[_OFFSET]]. Add bytes to change position. :: ''name'''''.SIZE''' is the remaining size of the block at current position in bytes AS [[_OFFSET]] :: ''name'''''.TYPE''' is the type (represented as bits combined to form a value) AS [[LONG]]: -:::''Supported from QB64 version .975 Onwards ([[Version .954]] returns different values!)'' -:::* [bit 0] 1* byte types ([[_BYTE]]) -:::* [bit 1] 2* byte types ([[INTEGER]]) -:::* [bit 2] 4* byte types ([[LONG]] or [[SINGLE]]) -:::* [bit 3] 8* byte types ([[DOUBLE]] or [[_INTEGER64]]) -:::* [bit 4] 16* byte types (reserved for future use) -:::* [bit 5] 32* byte types ([[_FLOAT]]) -:::* [bit 6] 64* byte types (reserved for future use) -:::* [bit 7] 128 = integer types ([[_BYTE]], [[INTEGER]], [[LONG]], [[_INTEGER64]]) (added to *) -:::* [bit 8] 256 = floating point types ([[SINGLE]], [[DOUBLE]], [[_FLOAT]]) (added to *) -:::* [bit 9] 512 = STRING types (fixed length or variable length) -:::* [bit 10] 1024 = [[_UNSIGNED]] types (added to *+128) -:::* [bit 11] 2048 = pixel data (added to 1+128+1024 or 4+128+1024) -:::* [bit 12] 4096 = _MEM TYPE structure (NOT added to 32768) -:::* [bit 13] 8192 = [[_OFFSET]] type (added to 4+128+[1024] or 8+128+[1024] or future_size+128+[1024]) -:::* [bit 14] 16384 = data created/defined by [[_MEMNEW]](size) or [[_MEMNEW]](offset,size) -:::* [bit 15] 32768 = a custom, user defined type (ie. created with [[TYPE]] name ... END TYPE) -:::* [bit 16] 65536 = an array of data (added to other type values defining the array's data type) -:::''If a future QB64 variable type has a size larger than 64 bytes no lower bits will be set.'' -:: ''name'''''.ELEMENTSIZE''' is the [[_BYTE]] size of the elements within the block AS [[_OFFSET]] -:::* 1 = [[_BYTE]] or unfixed [[STRING]] values have a size of 1 byte. -:::* 2 = [[INTEGER]] values have an element size of 2 bytes -:::* 4 = [[LONG]] integer and [[SINGLE]] float values have an element size of 4 bytes -:::* 8 = [[DOUBLE]] float and [[_INTEGER64]] values have an element size of 8 bytes -:::* 32 = [[_FLOAT]] values have an element size of 32 bytes -:::* [[LEN]] = [[_OFFSET]] and fixed length [[STRING]] byte sizes vary so use [[LEN]] for the number of bytes. -:: ''name'''''.IMAGE''' is the handle used if [[_MEMIMAGE]](handle) was used to initialize the _MEM block -* '''Note: [[_OFFSET]] values cannot be cast to other variable [[type]]s reliably! _MEM is a reserved custom variable [[type]]!''' -* '''[[_MEM (function)|_MEM]] cannot reference variable length [[STRING]] variable values! String values must be designated as a fixed [[LEN]].''' +==.TYPE values (version 1.000 and up)== +:::* 0 = UDT ([[TYPE|user defined type]]) or memory created by [[_MEMNEW]] +:::* 1 = 1 bit ELEMENT.SIZE=1 *Only used along with specific types (currently integers or floats) +:::* 2 = 2 bit. ELEMENT.SIZE=2 * +:::* 4 = 4 bit. ELEMENT.SIZE=4 * +:::* 8 = 8 bit. ELEMENT.SIZE=8 * +:::* 16 = 16 bit. ELEMENT.SIZE=16 * +:::* 32 = 32 bit. ELEMENT.SIZE=32 * +:::* 64 = 64 bit. ELEMENT.SIZE=64 * +:::* 128 = 128 bit. ELEMENT.SIZE=128 * +:::* 256 = 256 bit. ELEMENT.SIZE=256 * +:::* 512(+ bit*) = integer types only(ie. whole numbers) +:::* 1024(+ bit*) = floating point types only(ie. numbers that can have a decimal point) +:::* 2048 = [[STRING]] type only +:::* 4096(+ 512 + bit*) = [[_UNSIGNED]] integer type only +:::* 8192 = [[_MEM]] type only +:::* 16384(+ 512 + bit*)= [[_OFFSET]] type only +''Note: If a future integer, float or other type doesn't have a size that is 1,2,4,8,16,32,64,128 or 256 it won't have a size-bit set.'' + +===Versions prior to 1.000=== +:::* 1 = Integer types such as [[_BYTE]], [[INTEGER]], [[LONG]], [[_INTEGER64]] or [[_OFFSET]] +:::* 2 = [[_UNSIGNED]] variable types. Value must be added to the variable type value.(2 cannot be used by itself) +:::* 3 = ALL [[_UNSIGNED]] [[INTEGER]] type values.(add 1 + 2) +:::* 4 = Floating point types such as [[SINGLE]], [[DOUBLE]] or [[_FLOAT]] +:::* 8 = [[STRING]] +:::* 0 = unknown(eg. created with [[_MEMNEW]]) or [[TYPE|user-defined-types]] + +* '''Note: [[_OFFSET]] values cannot be cast to other variable [[type]]s reliably. _MEM is a reserved custom variable [[type]].''' +* '''[[_MEM (function)|_MEM]] cannot reference variable length [[STRING]] variable values. String values must be designated as a fixed-[[LEN|length]] string.''' +{{PageExamples}} ''Example 1:'' Demonstration of .IMAGE to determine an image's dimensions, .TYPE to verify the type and [[_MEMEXISTS]] to check image has not been freed {{CodeStart}} {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(500, 500, 32) @@ -80,7 +83,7 @@ t = m.{{Cl|TYPE}} {{CodeEnd}} -''Example 2:'' Converts the current [[_DEST|destination]] [[SCREEN]] 13 image memory altered by [[PSET]] to a [[STRING]] value. SCREEN 13 only! +''Example 2:'' Converts the current [[_DEST|destination]] [[SCREEN]] 13 image memory altered by [[PSET]] to a [[STRING]] value. SCREEN 13 only. {{CodeStart}} '' '' {{Cl|SCREEN}} 13 {{Cl|PSET}} (0, 0), {{Cl|ASC}}("H") 'top left corner of screen @@ -107,7 +110,38 @@ HELLO m.ELEMENTSIZE = 1 byte {{WhiteEnd}} -''See also:'' +''Example 3:'' Using _MEM to convert _OFFSET to _INTEGER64. +{{CodeStart}} '' '' +DIM x AS INTEGER +DIM m AS _MEM +m = _MEM(x) +PRINT m.OFFSET +PRINT ConvertOffset(m.OFFSET) + + +FUNCTION ConvertOffset&& (value AS _OFFSET) +$CHECKING:OFF +DIM m AS _MEM 'Define a memblock +m = _MEM(value) 'Point it to use value +$IF 64BIT THEN + 'On 64 bit OSes, an OFFSET is 8 bytes in size. We can put it directly into an Integer64 + _MEMGET m, m.OFFSET, ConvertOffset&& 'Get the contents of the memblock and put the values there directly into ConvertOffset&& +$ELSE + 'However, on 32 bit OSes, an OFFSET is only 4 bytes. We need to put it into a LONG variable first + _MEMGET m, m.OFFSET, temp& 'Like this + ConvertOffset&& = temp& 'And then assign that long value to ConvertOffset&& +$END IF +_MEMFREE m 'Free the memblock +$CHECKING:ON +END FUNCTION + +{{CodeEnd}} + +''Explanation:'' The above will print two numbers for us which should match. These numbers will vary, as they're representations of where X is stored in memory, and that position is going to vary every time the program is run. What it should illustrate, however, is a way to convert _OFFSET to _INTEGER64 values, which can sometimes be useful when trying to run calculations involving mem.SIZE, mem.TYPE, or mem.ELEMENTSIZE. + + + +{{PageSeeAlso}} * [[_MEM (function)]] * [[_MEMELEMENT]], [[_MEMCOPY]] * [[_MEMIMAGE]], [[_MEMNEW]] diff --git a/internal/help/_MEMCOPY.txt b/internal/help/_MEMCOPY.txt index 77e02d488..873dcbd75 100644 --- a/internal/help/_MEMCOPY.txt +++ b/internal/help/_MEMCOPY.txt @@ -1,26 +1,27 @@ {{DISPLAYTITLE:_MEMCOPY}} -The '''_MEMCOPY''' statement copies a block of bytes from one memory offset TO another offset in memory. +The [[_MEMCOPY]] statement copies a block of bytes from one memory offset to another offset in memory. {{PageSyntax}} -:: '''_MEMCOPY ''source_block'', ''source_block.OFFSET'', ''source_block.SIZE'' [[TO]] ''dest_block'', ''dest_block.OFFSET''''' +: [[_MEMCOPY]] {{Parameter|sourceBlock}}, {{Parameter|sourceBlock.OFFSET}}, {{Parameter|sourceBlock.SIZE}} [[TO]] {{Parameter|destBlock}}, {{Parameter|destBlock.OFFSET}} {{Parameters}} -* ''source block'' is the source memory block name created AS [[_MEM]]. -* ''source block.OFFSET'' is the dot [[_OFFSET]] within the source memory block to read from. -* ''source block.SIZE'' is the total number of bytes to transfer based on actual size. -* ''dest block'' is the destination [[_MEM]] memory block name to transfer data to. -* ''dest block.OFFSET'' is the dot [[_OFFSET]] within the dest [[_MEM]] memory block to write to. +* {{Parameter|sourceBlock}} is the source memory block name created AS [[_MEM]]. +* {{Parameter|sourceBlock.OFFSET}} is the dot [[_OFFSET]] within the source memory block to read from. +* {{Parameter|sourceBlock.SIZE}} is the total number of bytes to transfer based on actual size. +* {{Parameter|destBlock}} is the destination [[_MEM]] memory block name to transfer data to. +* {{Parameter|destBlock.OFFSET}} is the dot [[_OFFSET]] within the dest [[_MEM]] memory block to write to. -''Usage:'' +{{PageDescription}} * The dot OFFSET is the memory block's start location in memory. Add bytes to place data further into the block. * The dot SIZE is the total byte size of the memory block to transfer. You can transfer all or a portion of the data bytes. * The memory block regions may overlap. -* '''Always free memory blocks after values have been transferred to variables and are no longer required!''' +* '''Always free memory blocks after values have been transferred to variables and are no longer required.''' +{{PageExamples}} ''Example:'' Swapping data from one [[STRING]] variable to another. Fixed length strings are recommended for speed. {{CodeStart}} '' '' {{Cl|DIM}} m {{Cl|AS}} {{Cl|_MEM}} @@ -61,7 +62,7 @@ b$ = {{Cl|SPACE$}}(10) {{TextEnd}} -''See also:'' +{{PageSeeAlso}} * [[_MEM]], [[_MEM (function)]] * [[_MEMNEW]], [[_MEMGET (function)]] * [[_MEMIMAGE]], [[_MEMELEMENT]] diff --git a/internal/help/_MEMELEMENT.txt b/internal/help/_MEMELEMENT.txt index b08545c0e..ff8c675f8 100644 --- a/internal/help/_MEMELEMENT.txt +++ b/internal/help/_MEMELEMENT.txt @@ -1,20 +1,27 @@ {{DISPLAYTITLE:_MEMELEMENT}} -The '''_MEMELEMENT''' function returns a [[_MEM]] block referring to a variable's memory ,but not past it. +The [[_MEMELEMENT]] function returns a [[_MEM]] block referring to a variable's memory, but not past it. {{PageSyntax}} -::: memory_block = '''_MEMELEMENT('''''reference_variable'')''' +: {{Parameter|memoryBlock}} = [[_MEMELEMENT]]({{Parameter|referenceVariable}}) -* The ''reference variable'' parameter designates the existing variable name using the memory block. +* The {{Parameter|referenceVariable}} parameter designates the existing variable name using the memory block. * _MEMELEMENT is the same as [[_MEM]] but in an array it returns the specifications of an element, not the entire array. * All values created by memory functions MUST be freed using [[_MEMFREE]] with a valid [[_MEM]] variable type. -* The _MEMELEMENT type contains the following '''read only''' DOT elements where ''name'' is the variable name: +* The _MEMELEMENT type contains the following '''read-only''' elements where ''name'' is the variable name: :: ''name'''''.OFFSET''' is the beginning offset of the memory block AS [[_OFFSET]] :: ''name'''''.SIZE''' returns the largest available region of memory of the ELEMENT in bytes AS [[_OFFSET]] -:: ''name'''''.TYPE''' is the type (represented as bits combined to form a value) AS [[LONG]]: +:: ''name'''''.ELEMENTSIZE''' is the [[_BYTE]] size of the elements within the block AS [[_OFFSET]] -'''WARNING: THE .TYPE VALUE HAS BEEN REVIEWED AND IN THE NEXT QB64 RELEASE WILL BE:''' +:::* 2 = [[INTEGER]] values have an element size of 2 bytes +:::* 4 = [[LONG]] integer and [[SINGLE]] float values have an element size of 4 bytes +:::* 8 = [[DOUBLE]] float and [[_INTEGER64]] values have an element size of 8 bytes +:::* 32 = [[_FLOAT]] values have an element size of 32 bytes +:::* [[LEN]] = [[STRING]] or [[_OFFSET]] byte sizes vary so use [[LEN]](variable) for the number of bytes. +:: ''name'''''.TYPE''' is the type (represented as bits combined to form a value) AS [[LONG]] (see below). + +==.TYPE values (version 1.000 and up)== :::* 0 = UDT ([[TYPE|user defined type]]) or memory created by [[_MEMNEW]] :::* 1 = 1 bit ELEMENT.SIZE=1 *Only used along with specific types (currently integers or floats) :::* 2 = 2 bit. ELEMENT.SIZE=2 * @@ -33,25 +40,18 @@ The '''_MEMELEMENT''' function returns a [[_MEM]] block referring to a variable' :::* 16384(+ 512 + bit*)= [[_OFFSET]] type only ''Note: If a future integer, float or other type doesn't have a size that is 1,2,4,8,16,32,64,128 or 256 it won't have a size-bit set.'' -'''THE CURRENT VERSION .954 ONLY METHOD WHICH WILL BE CHANGED IS AS FOLLOWS:''' +===Versions prior to 1.000=== :::* 1 = Integer types such as [[_BYTE]], [[INTEGER]], [[LONG]], [[_INTEGER64]] or [[_OFFSET]] :::* 2 = [[_UNSIGNED]] variable types. Value must be added to the variable type value.(2 cannot be used by itself) :::* 3 = ALL [[_UNSIGNED]] [[INTEGER]] type values.(add 1 + 2) :::* 4 = Floating point types such as [[SINGLE]], [[DOUBLE]] or [[_FLOAT]] :::* 8 = [[STRING]] :::* 0 = unknown(eg. created with [[_MEMNEW]]) or [[TYPE|user-defined-types]] -'''THIS CHANGE WILL NOT AFFECT ANY OTHER ASPECT OF THE _MEM SYSTEM.''' -:: ''name'''''.ELEMENTSIZE''' is the [[_BYTE]] size of the elements within the block AS [[_OFFSET]] - -:::* 2 = [[INTEGER]] values have an element size of 2 bytes -:::* 4 = [[LONG]] integer and [[SINGLE]] float values have an element size of 4 bytes -:::* 8 = [[DOUBLE]] float and [[_INTEGER64]] values have an element size of 8 bytes -:::* 32 = [[_FLOAT]] values have an element size of 32 bytes -:::* [[LEN]] = [[STRING]] or [[_OFFSET]] byte sizes vary so use [[LEN]](variable) for the number of bytes. -<center>'''Note: [[_MEM]] and [[_OFFSET]] values cannot be cast to other variable types!'''</center> +<center>'''Note: [[_MEM]] and [[_OFFSET]] values cannot be cast to other variable types.'''</center> +{{PageExamples}} ''Example:'' Comparing the specifications returned by [[_MEM]] and _MEMELEMENT from an array. {{CodeStart}} '' '' {{Cl|DIM}} a(1 {{Cl|TO}} 100) {{Cl|AS}} {{Cl|_UNSIGNED}} {{Cl|_BYTE}} @@ -75,7 +75,7 @@ m2 = {{Cl|_MEMELEMENT}}(a(50)) 'function returns information about the specific ::* [[_MEMELEMENT]] value returns the available element .SIZE as one byte. -''See also:'' +{{PageSeeAlso}} * [[_MEM]] * [[_MEMNEW]] * [[_MEMGET]], [[_MEMPUT]] diff --git a/internal/help/_MEMEXISTS.txt b/internal/help/_MEMEXISTS.txt index 068b1bfac..82df17aa5 100644 --- a/internal/help/_MEMEXISTS.txt +++ b/internal/help/_MEMEXISTS.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_MEMEXISTS}} -The '''_MEMEXISTS''' function returns true (-1) if the memory block variable name specified exists in memory and false (0) if it does not. +The [[_MEMEXISTS]] function returns true (-1) if the memory block variable name specified exists in memory and false (0) if it does not. {{PageSyntax}} -::: ret = '''[[_MEMEXISTS]] ('''''memblock''''')''' +: {{Parameter|result}} = [[_MEMEXISTS]]({{Parameter|memBlock}}) -''Details:'' -* The memblock variable name should have been created using [[DIM]] blockname [[AS]] [[_MEM]] type ([[DIM]]. -* The function verifies that the memory variable exists in memory before using a passed block to avoid generating QB64 errors. -* Typically, this function is used by a [[DECLARE LIBRARY|LIBRARY]] [[SUB]] or [[FUNCTION]] which accepts a [[_MEM]] structure as input to avoid an error. +{{PageDescription}} +* The {{Parameter|memBlock}} variable name must have been created using [[DIM]] memBlock [[AS]] [[_MEM]] type ([[DIM]]. +* The function verifies that the memory variable exists in memory before using a passed block, to avoid generating QB64 errors. +* Typically, this function is used by a [[DECLARE LIBRARY|LIBRARY]] [[SUB]] or [[FUNCTION]] which accepts a [[_MEM]] structure as input, to avoid an error. -''See Also:'' +{{Parameter|See Also:}} * [[_MEM (function)]] * [[_MEMELEMENT]], [[_MEMCOPY]] * [[_MEMIMAGE]], [[_MEMNEW]] diff --git a/internal/help/_MEMFILL.txt b/internal/help/_MEMFILL.txt index d3779ab12..80b02efda 100644 --- a/internal/help/_MEMFILL.txt +++ b/internal/help/_MEMFILL.txt @@ -1,23 +1,24 @@ {{DISPLAYTITLE:_MEMFILL}} -The '''_MEMFILL''' statement converts a value to a specified type then fills memory with that type including any non-whole remainder. +The [[_MEMFILL]] statement converts a value to a specified type, then fills memory with that type including any non-whole remainder. {{PageSyntax}} -::: '''_MEMFILL''' ''memory_block'', ''memory_block.OFFSET'', ''fill_bytes'', ''value''''' [AS variable_type] +: [[_MEMFILL]] {{Parameter|memoryBlock}}, {{Parameter|memoryBlock.OFFSET}}, {{Parameter|fillBytes}}, {{Parameter|value}} [AS {{Parameter|variableType}}] {{Parameters}} -* The ''memory block'' [[_MEM]] memory block is the block referenced to be filled. -* The ''offset'' is the starting offset of the above referenced memory block. -* The ''fill bytes'' is the number of bytes to fill the memory block. -* The ''value'' is the value to place in the memory block at the designated OFFSET position. -* A literal or variable ''value'' can be optionally set [[AS]] a variable [[type]] appropriate for the memory block. +* The {{Parameter|memoryBlock}} [[_MEM]] memory block is the block referenced to be filled. +* {{Parameter|memoryBlock.OFFSET}} is the starting offset of the above referenced memory block. +* The {{Parameter|fillBytes}} is the number of bytes to fill the memory block. +* The {{Parameter|value}} is the value to place in the memory block at the designated OFFSET position. +* A literal or variable {{Parameter|value}} can be optionally set [[AS]] a variable [[type]] appropriate for the memory block. -''Usage:'' -* To clear previous data from a [[_MEMNEW]] memory block, use _MEMFILL with a zero ''value''. +{{PageDescription}} +* To clear previous data from a [[_MEMNEW]] memory block, use _MEMFILL with a {{Parameter|value}} of 0. +{{PageExamples}} ''Example:'' Filling array values quickly using FOR loops or a simple memory fill. {{CodeStart}} '' '' {{Cl|DIM}} a(100, 100) {{Cl|AS}} {{Cl|LONG}} @@ -38,7 +39,7 @@ mema = {{Cl|_MEM (function)|_MEM}}(b()) {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_MEM]], [[_MEM (function)]] * [[_MEMIMAGE]], [[_MEMNEW]] * [[_MEMGET]], [[_MEMPUT]] diff --git a/internal/help/_MEMFREE.txt b/internal/help/_MEMFREE.txt index ffe2d0fef..2e0f1ece2 100644 --- a/internal/help/_MEMFREE.txt +++ b/internal/help/_MEMFREE.txt @@ -1,21 +1,21 @@ {{DISPLAYTITLE:_MEMFREE}} -The '''_MEMFREE''' statement frees the designated memory block [[_MEM]] value and MUST be used with all memory functions. +The [[_MEMFREE]] statement frees the designated memory block [[_MEM]] value and must be used with all memory functions. {{PageSyntax}} -::: '''_MEMFREE ''memory_variable''''' +: [[_MEMFREE]] {{Parameter|memoryVariable}} {{Parameters}} -* ALL designated [[_MEM]] type ''memory variable'' values must be freed to conserve memory when they are no longer used or needed. +* ALL designated [[_MEM]] type {{Parameter|memoryVariable}} values must be freed to conserve memory when they are no longer used or needed. -''Usage:'' -* Since all [[_MEM]] type variables cannot use a suffix, use [[DIM]] ''variable'' [[AS]] [[_MEM]] to create memory handle variables. -* All values created by memory functions MUST be freed using [[_MEMFREE]] with a valid [[_MEM]] variable. +{{PageDescription}} +* Since [[_MEM]] type variables cannot use a suffix, use [[DIM]] {{Parameter|memoryVariable}} [[AS]] [[_MEM]] to create memory handle variables. +* All values created by memory functions must be freed using [[_MEMFREE]] with a valid [[_MEM]] variable. -''See also:'' +{{PageSeeAlso}} * [[_MEM]] {{text|(variable type)}} * [[_MEM (function)]] * [[_MEMNEW]] {{text|(function)}} diff --git a/internal/help/_MEMGET.txt b/internal/help/_MEMGET.txt index fe074f492..351df873f 100644 --- a/internal/help/_MEMGET.txt +++ b/internal/help/_MEMGET.txt @@ -1,24 +1,25 @@ {{DISPLAYTITLE:_MEMGET}} -The '''_MEMGET''' statement reads a portion of a memory block at an OFFSET position into a variable, array or user defined type. +The [[_MEMGET]] statement reads a portion of a memory block at an OFFSET position into a variable, array or user defined type. {{PageSyntax}} -::: '''_MEMGET ''memory_block'', ''byte_position'', ''holding_variable''''' +: [[_MEMGET]] {{Parameter|memoryBlock}}, {{Parameter|bytePosition}}, {{Parameter|destinationVariable}} -* ''memory block'' is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. -* mandatory ''byte_position'' is the ''memory_block.[[OFFSET]]'' memory start position plus any bytes to move into the block. -* ''holding variable'' is the variable assigned to hold the data. The number of bytes read is determined by the variable [[type]] used. +* {{Parameter|memoryBlock}} is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. +* {{Parameter|bytePosition}} is the {{Parameter|memoryBlock}}.[[OFFSET]] memory start position plus any bytes to move into the block. +* {{Parameter|destinationVariable}} is the variable assigned to hold the data. The number of bytes read is determined by the variable [[type]] used. -''Usage:'' -* The _MEMGET statement is similar to the [[GET]] statement used in files, but the position is required. +{{PageDescription}} +* The [[_MEMGET]] statement is similar to the [[GET]] statement used in files, but the position is required. * The memory block name.[[OFFSET]] returns the starting byte position of the block. Add bytes to move into the block. -* The variable type held in the memory block can determine the next ''byte position'' to read. -* [[LEN]](variable) can determine the byte size of numerical or user defined variable [[type]]s irregardless of the value held. +* The variable type held in the memory block can determine the next {{Parameter|bytePosition}} to read. +* [[LEN]] can be used to determine the byte size of numerical or user defined variable [[type]]s regardless of the value held. * [[STRING]] values should be of a defined length. Variable length strings can actually move around in memory and not be found. +{{PageExamples]] ''Example:'' Shows how to read the PSET color values from a program's [[SCREEN]] memory to an array. {{CodeStart}} '' '' {{Cl|SCREEN}} 13 @@ -40,7 +41,7 @@ m = {{Cl|_MEMIMAGE}} '0 or no handle necessary when accessing the current progr {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_MEMGET (function)]] * [[_MEMPUT]] * [[_MEM]] diff --git a/internal/help/_MEMGET_(function).txt b/internal/help/_MEMGET_(function).txt index 727f6e84d..b4ea30db3 100644 --- a/internal/help/_MEMGET_(function).txt +++ b/internal/help/_MEMGET_(function).txt @@ -1,26 +1,27 @@ {{DISPLAYTITLE:_MEMGET (function)}} -The '''_MEMGET''' function returns a value from a specific memory block name at the specified OFFSET using a certain variable type. +The [[_MEMGET]] function returns a value from a specific memory block name at the specified OFFSET using a certain variable type. {{PageSyntax}} -::: returnvalue = '''_MEMGET(''memory_block'', ''byte_position'', ''variable_type'')''' +: {{Parameter|returnValue}} = [[_MEMGET]]({{Parameter|memoryBlock}}, {{Parameter|bytePosition}}, {{Parameter|variableType}}) {{Parameters}} -* Returns a value of the ''variable type'' designated. The holding variable must match that [[TYPE]]! -* ''memory block'' is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. -* mandatory ''byte_position'' is the ''memory_block.[[OFFSET]]'' memory start position plus any bytes to move into the block. -* ''variable type'' is a variable [[TYPE]] like [[_BYTE]], [[INTEGER]], [[SINGLE]], [[DOUBLE]], etc. +* Returns a value of the {{Parameter|variableType}} designated. The holding variable must match that [[TYPE]]. +* {{Parameter|memoryBlock}} is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. +* {{Parameter|bytePosition}} is the {{Parameter|memoryBlock}}.[[OFFSET]] memory start position plus any bytes to move into the block. +* {{Parameter|variableType}} is a variable [[TYPE]] like [[_BYTE]], [[INTEGER]], [[SINGLE]], [[DOUBLE]], etc. -''Usage:'' -* The memory block name.[[OFFSET]] returns the starting byte position of the block. Add bytes to move into the block. -* The variable type held in the memory block can determine the next ''byte position'' to read. -* [[LEN]](variable) can determine the byte size of numerical or user defined variable [[type]]s irregardless of the value held. +{{PageDescription}} +* {{Parameter|memoryBlock}}.[[OFFSET]] returns the starting byte position of the block. Add bytes to move into the block. +* The variable type held in the memory block can determine the next {{Parameter|bytePosition}} to read. +* [[LEN]] can be used to determine the byte size of numerical or user defined variable [[type]]s regardless of the value held. * [[STRING]] values should be of a defined length. Variable length strings can actually move around in memory and not be found. -* '''_MEMGET variable values that are assigned a variable [[type]] other than a memory type do not need to be freed!''' +* '''_MEMGET variable values that are assigned a variable [[type]] other than a memory type do not need to be freed.''' +{{PageExamples}} ''Example:'' [[DEF SEG]] and [[VARPTR]] are no longer necessary to do things in memory just like [[POKE]] and [[PEEK]] do. {{CodeStart}} '' '' {{Cl|DIM}} o {{Cl|AS}} {{Cl|_MEM}} @@ -34,7 +35,7 @@ v = {{Cl|_MEMGET (function)|_MEMGET}}(o, o.OFFSET + 1, {{Cl|_UNSIGNED}} {{Cl|_BY :''Explanation:'' The memory block and OFFSET are given by [[_MEMPUT]] and the _MEMGET function, with the designated type. -''See also:'' +{{PageSeeAlso}} * [[_MEM]], [[MEM (function)]] * [[_MEMGET]], [[_MEMPUT]] * [[_MEMNEW]], [[_MEMFILL]] diff --git a/internal/help/_MEMIMAGE.txt b/internal/help/_MEMIMAGE.txt index 4f91c83c0..88666ed0c 100644 --- a/internal/help/_MEMIMAGE.txt +++ b/internal/help/_MEMIMAGE.txt @@ -1,22 +1,23 @@ {{DISPLAYTITLE:_MEMIMAGE}} -The '''_MEMIMAGE''' function returns a [[_MEM]] value referring to an image's memory using a designated image handle. +The [[_MEMIMAGE]] function returns a [[_MEM]] value referring to an image's memory using a designated image handle. {{PageSyntax}} -::: image_block = '''_MEMIMAGE'''[(''image_handle'')] +: {{Parameter|imageBlock}} = [[_MEMIMAGE]][({{Parameter|imageHandle&}})] {{Parameters}} -* The ''image block'' [[_MEM]] type variable holds the read only .OFFSET, .SIZE, .TYPE and .ELEMENTSIZE. -* The optional ''image handle'' requires no parameter or 0 if the image desired is the current [[_DEST]]ination program screen image. +* The {{Parameter|imageBlock}} [[_MEM]] type variable holds the read-only elements .OFFSET, .SIZE, .TYPE and .ELEMENTSIZE. +* If the optional {{Parameter|imageHandle&}} isn't passed, it is assumed to be the current [[_DEST]]ination program screen image. -''Usage:'' +{{PageDescription}} * Use the function to place images into memory access blocks for faster data access. -* All values created by this function MUST be freed using [[_MEMFREE]] with a valid [[_MEM]] [[type]] variable. +* All values created by this function must be freed using [[_MEMFREE]] with a valid [[_MEM]] [[type]] variable. * Image handle values and the memory used must still be freed using [[_FREEIMAGE]] when no longer required. +{{PageExamples}} ''Example 1:'' Darkening an image using memory with [[$CHECKING]]:OFF for greater speed. Use any 24 bit image file name on the second code line. {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(1024, 768, 32) @@ -79,13 +80,13 @@ x1$ = {{Cl|_MEMGET (function)|_MEMGET}}(m, m.OFFSET, {{Cl|STRING}} * 11) 'conver : ''Notes:'' The colors in the upper left corner are the text data used. An image could hold a hidden text message this way. -''See also:'' +{{PageSeeAlso}} * [[_MEM]] * [[_MEMNEW]] * [[_MEMGET]], [[_MEMPUT]] * [[_MEMFREE]] * [[$CHECKING]] -* [http://www.qb64.net/forum/index.php?topic=11052.0 Reading pixel colors faster using _MEMIMAGE] +* [http://www.qb64.net/forum/index.php?topic=11052.0 Reading pixel colors faster using _MEMIMAGE] (forum post) {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MEMNEW.txt b/internal/help/_MEMNEW.txt index 3171d46c6..5eb820870 100644 --- a/internal/help/_MEMNEW.txt +++ b/internal/help/_MEMNEW.txt @@ -1,25 +1,26 @@ {{DISPLAYTITLE:_MEMNEW}} -The '''_MEMNEW''' function allocates new memory and returns a [[_MEM]] memory block referring to it. +The [[_MEMNEW]] function allocates new memory and returns a [[_MEM]] memory block referring to it. {{PageSyntax}} -::: memory_block = '''_MEMNEW(''byte_size'')''' +: {{Parameter|memoryBlock}} = [[_MEMNEW]]({{Parameter|byteSize}}) {{Parameters}} -* The ''byte size'' parameter is the desired byte size of the memory block based on the variable [[type]] it will hold. +* The {{Parameter|byteSize}} parameter is the desired byte size of the memory block based on the variable [[type]] it will hold. -''Usage:'' -* The ''memory block'' value created holds the starting OFFSET, SIZE, TYPE and ELEMENTSIZE. -* _MEMNEW does not clear the data previously in the memory block it allocates for speed purposes. -* To clear previous data from a new memory block, use [[_MEMFILL]] with a zero byte value, -* When a new memory block is created the memory .TYPE value will be 0.(this may be changeable in the future) -* '''If the read only memory block .SIZE is 0, the memory block was not created!''' -* '''All values created by memory functions MUST be freed using [[_MEMFREE]] with a valid [[_MEM]] variable.''' +{{PageDescription}} +* The {{Parameter|memoryBlock}} value created holds the elements .OFFSET, .SIZE, .TYPE and .ELEMENTSIZE. +* [[_MEMNEW]] does not clear the data previously in the memory block it allocates, for speed purposes. +* To clear previous data from a new memory block, use [[_MEMFILL]] with a byte value of 0. +* When a new memory block is created the memory .TYPE value will be 0. +* '''If the read only memory block .SIZE is 0, the memory block was not created.''' +* '''All values created by memory functions must be freed using [[_MEMFREE]] with a valid [[_MEM]] variable.''' -''Example:'' Shows how [[SINGLE]] numerical values can be passed, but unfixed [[STRING]] lengths cannot get the value. +{{PageExamples}} +''Example:'' Shows how [[SINGLE]] numerical values can be passed, but non-fixed [[STRING]] lengths cannot get the value. {{CodeStart}} '' '' {{Cl|DIM}} m {{Cl|AS}} {{Cl|_MEM}} {{Cl|DIM}} f {{Cl|AS}} {{Cl|STRING}} * 5 @@ -44,7 +45,7 @@ f = Doggy 5 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_MEM]], [[_MEMPUT]] * [[_MEMGET]], [[_MEMGET (function)]] * [[_MEMFILL]], [[_MEMFREE]] diff --git a/internal/help/_MEMPUT.txt b/internal/help/_MEMPUT.txt index 42f65a494..4dd865d9e 100644 --- a/internal/help/_MEMPUT.txt +++ b/internal/help/_MEMPUT.txt @@ -1,26 +1,27 @@ {{DISPLAYTITLE:_MEMPUT}} -The '''_MEMPUT''' statement writes data to a portion of a designated memory block at an OFFSET position. +The [[_MEMPUT]] statement writes data to a portion of a designated memory block at an [[OFFSET]] position. {{PageSyntax}} -::: '''_MEMPUT''' ''memory_block'', ''byte_position'', ''source_variable'' [AS ''type''] +: [[_MEMPUT]] {{Parameter|memoryBlock}}, {{Parameter|bytePosition}}, {{Parameter|sourceVariable}} [AS {{Parameter|type}}] {{Parameters}} -* ''memory block'' is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. -* ''byte_position'' is the ''memory block.[[OFFSET]]'' start position plus any bytes needed to read specific values. -* The ''source variable'' type designates the size and ''byte position'' it should be written to. It can be a variable, [[arrays|array]] or user defined type. -* The ''source variable'' can be converted [[AS]] a specific variable ''[[TYPE|type]]'' before being written to the ''memory block offset'' as bytes. +* {{Parameter|memoryBlock}} is a [[_MEM]] variable type memory block name created by [[_MEMNEW]] or the [[_MEM (function)|_MEM]] function. +* {{Parameter|bytePosition}} is the {{Parameter|memoryBlock}}.[[OFFSET]] start position plus any bytes needed to read specific values. +* The {{Parameter|sourceVariable}} type designates the size and {{Parameter|bytePosition}} it should be written to. It can be a variable, [[arrays|array]] or user defined type. +* {{Parameter|bytePosition}} can be converted [[AS]] a specific variable ''[[TYPE|type]]'' before being written to the {{Parameter|memoryBlock}} as bytes. -''Usage:'' -* The _MEMPUT statement is similar to the [[PUT]] file statement, but the ''byte position'' is required. -* The memory block name.[[OFFSET]] returns the starting byte position of the block. Add bytes to move into the block. +{{PageDescription}} +* The _MEMPUT statement is similar to the [[PUT]] file statement, but {{Parameter|bytePosition}} is required. +* The {{Parameter|memoryBlock}}.[[OFFSET]] returns the starting byte position of the block. Add bytes to move into the block. * The variable type held in the memory block can determine the next ''byte position'' to write a value. -* [[LEN]](variable) can determine the byte size of numerical or user defined variable [[type]]s irregardless of the value held. +* [[LEN]] can be used to determine the byte size of numerical or user defined variable [[type]]s regardless of the value held. * [[STRING]] values should be of a defined length. Variable length strings can actually move around in memory and not be found. +{{PageDescription}} ''Example:'' _MEMPUT can be used just like [[POKE]] without [[DEF SEG]]. {{CodeStart}} '' '' {{Cl|DIM}} o {{Cl|AS}} {{Cl|_MEM}} @@ -32,7 +33,7 @@ v = {{Cl|_MEMGET (function)|_MEMGET}}(o, o.OFFSET + 1, {{Cl|_UNSIGNED}} {{Cl|_BY {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_MEMGET]], [[_MEMGET (function)]] * [[_MEM]], [[_MEM (function)]] * [[_MEMIMAGE]], [[_MEMNEW]] diff --git a/internal/help/_MEM_(function).txt b/internal/help/_MEM_(function).txt index 41258140d..e16984b31 100644 --- a/internal/help/_MEM_(function).txt +++ b/internal/help/_MEM_(function).txt @@ -1,26 +1,27 @@ {{DISPLAYTITLE:_MEM (function)}} -The '''_MEM''' function returns a _MEM block referring to the largest possible continuous memory region beginning at variable's offset. +The [[_MEM]] function returns a _MEM block referring to the largest possible continuous memory region beginning at a variable's offset. {{PageSyntax}} -::: memory_block = '''_MEM(''reference_ variable'')''' +: {{Parameter|memoryBlock}} = [[_MEM]]({{Parameter|referenceVariable}}) -Unsecure {{PageSyntax}} -::: memory_block = '''_MEM(''offset'', ''byte_size'')''' +===Unsecure syntax=== +: {{Parameter|memoryBlock}} = [[_MEM]]({{Parameter|offset}}, {{Parameter|byteSize}}) {{Parameters}} -* The ''memory block'' created will hold the ''reference variable''' or [[arrays|array]] value(s), type and byte size in a separate memory area. -* The secure syntax ''reference variable'' is an existing variable's referenced memory block. -* The unsecure syntax's designated ''offset'' and ''byte size'' cannot be guaranteed! '''AVOID if possible!''' +* The {{Parameter|memoryBlock}} created will hold the {{Parameter|referenceVariable}} or [[arrays|array]] value(s), type and byte size in a separate memory area. +* The secure syntax {{Parameter|referenceVariable}} is an existing variable's referenced memory block. +* The unsecure syntax's designated {{Parameter|offset}} and {{Parameter|byteSize}} cannot be guaranteed. '''Avoid if possible.''' -''Usage:'' -* The ''memory block'' [[_MEM]] type variable holds the read only OFFSET, SIZE, TYPE and ELEMENTSIZE. +{{PageDescription}} +* The {{Parameter|memoryBlock}} [[_MEM]] type variable holds the following read-only elements: OFFSET, SIZE, TYPE and ELEMENTSIZE. * All values created by memory functions MUST be freed using [[_MEMFREE]] with a valid [[_MEM]] variable type. -* '''_MEM function cannot reference variable length [[STRING]] variable values! String values must be designated as a fixed [[LEN]].''' +* '''_MEM function cannot reference variable length [[STRING]] variable values. String values must be designated as a fixed-[[LEN|length]] string.''' +{{PageExamples}} ''Example:'' Assigning values to reference variables in memory. {{CodeStart}} '' '' {{Cl|DIM}} {{Cl|SHARED}} m(3) {{Cl|AS}} {{Cl|_MEM}} @@ -58,8 +59,8 @@ Saved(3) = n3 {{CodeEnd}}{{small|Code by SMcNeill}} -''See also:'' -* [[_MEM]] {{text|(varible type)}} +{{PageSeeAlso}} +* [[_MEM]] {{text|(variable type)}} * [[_MEMNEW]], [[_MEMCOPY]] * [[_MEMGET]], [[_MEMPUT]] * [[_MEMFILL]], [[_MEMIMAGE]] diff --git a/internal/help/_MK$.txt b/internal/help/_MK$.txt index 236bf0efe..8d2459040 100644 --- a/internal/help/_MK$.txt +++ b/internal/help/_MK$.txt @@ -1,19 +1,24 @@ {{DISPLAYTITLE:_MK$}}{{DISPLAYTITLE:}} -The '''_MK$''' function can convert any numerical type into an [[ASCII]] [[STRING]] value that must be converted back using [[_CV]]. +The [[_MK$]] function can convert any numerical type into an [[ASCII]] [[STRING]] value that can be converted back using [[_CV]]. {{PageSyntax}} -:{{Parameter|string_value$}} = {{KW|_MK$}}({{Parameter|numerical_type}}, {{Parameter|numerical_value}}) +:{{Parameter|string_value$}} = [[_MK$]]({{Parameter|numericalType}}, {{Parameter|numericalValue}}) + + +{{Parameters}} +* {{Parameter|numericalType}} is any QB64 numerical type: [[INTEGER]], [[LONG]], [[SINGLE]], [[DOUBLE]], [[_INTEGER64]], [[_BYTE]] or [[_BIT]]. +* Whole integer values can be signed or [[_UNSIGNED]]. +* {{Parameter|numericalValue}} must match the {{Parameter|numericalType}} used. {{PageDescription}} -* The numerical type is any QB or QB64 number type including: {{KW|INTEGER}}, {{KW|LONG}}, {{KW|SINGLE}}, {{KW|DOUBLE}}, {{KW|_INTEGER64}}, {{KW|_UNSIGNED}}, {{KW|_BYTE}} or {{KW|_BIT}}. -* The actual numerical value must match the numerical type used. -* Supports converting any Qbasic or '''QB64''' numerical value into a string value. +* Supports converting any QBasic or '''QB64''' numerical value into a string value. * Some resulting [[ASCII]] string characters might not be able to be printed to the screen. {{PageSeeAlso}} +* [[_CV]] {{text|(QB64 conversion function)}} * [[MKI$]], [[CVI]], [[INTEGER]] * [[MKL$]], [[CVL]], [[LONG]] * [[MKS$]], [[CVS]], [[SINGLE]] diff --git a/internal/help/_MOUSEBUTTON.txt b/internal/help/_MOUSEBUTTON.txt index e296877b2..8d33d3515 100644 --- a/internal/help/_MOUSEBUTTON.txt +++ b/internal/help/_MOUSEBUTTON.txt @@ -1,28 +1,28 @@ {{DISPLAYTITLE:_MOUSEBUTTON}} -The '''_MOUSEBUTTON''' Function returns the button status of a specified mouse button when read after [[_MOUSEINPUT]]. +The [[_MOUSEBUTTON]] function returns the button status of a specified mouse button when read after [[_MOUSEINPUT]]. {{PageSyntax}} -:: buttonstatus% = '''_MOUSEBUTTON('''''button_number''''')''' +: {{Parameter|buttonStatus%%}} = [[_MOUSEBUTTON]]({{Parameter|buttoNumber}}) {{Parameters}} -* [[INTEGER]] ''button number'' designates the mouse button to read (currently just the top 3). -:* 1 = Left mouse button -:* 2 = Right mouse button -:* 3 = Center or scroll button +* [[INTEGER]] {{Parameter|buttoNumber}} designates the mouse button to read (See [[_DEVICES]] for more than 3). +** 1 = Left mouse button +** 2 = Right mouse button +** 3 = Center or scroll button -''Usage:'' -* Returns -1 if the corresponding numbered ''button'' is pressed and zero when released. -* The ''button'' parameter is 1 for the Left button, 2 for the right and 3 for the center button. Other buttons are currently not available. -* Read [[_MOUSEINPUT]] FIRST to return the current button up or down status. (See Example 2) +{{PageDescription}} +* Returns -1 if the corresponding {{Parameter|buttoNumber}} is pressed or zero when released. +* Read [[_MOUSEINPUT]] first to return the current button up or down status. (See Example 2) * Button clicks and mouse movements will be remembered and should be cleared after an [[INPUT]] statement or other interruption. * To clear unread mouse input, use a [[_MOUSEINPUT]] loop that loops until it returns 0. * Use [[_DEVICE$]] to find the "[MOUSE]" [[_DEVICES]] number to find the number of buttons available using [[_LASTBUTTON]]. * '''Note:''' The center mouse button can also be read as [[_BUTTON]](2) on [[_DEVICEINPUT]](2) when a mouse is present. +{{PageExamples}} ''Example 1:'' Finding the number of mouse buttons available in QB64. This could also be used for other controller devices. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} d = 1 {{Cl|TO}} {{Cl|_DEVICES}} 'number of input devices found @@ -167,8 +167,7 @@ y = {{Cl|_MOUSEY}} * [[_MOUSESHOW]], [[_MOUSEHIDE]] * [[_DEVICES]], [[_DEVICE$]], [[_LASTBUTTON]] * [[_BUTTON]], [[_BUTTONCHANGE]] {{text|([[DEVICES|devices]])}} -* [[Controller_Devices]] -* [[SDL_Libraries#Mouse_Button|SDL Mouse Button Down Library]] +* [[Controller Devices]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSEHIDE.txt b/internal/help/_MOUSEHIDE.txt index 0ac706741..89b596743 100644 --- a/internal/help/_MOUSEHIDE.txt +++ b/internal/help/_MOUSEHIDE.txt @@ -1,16 +1,9 @@ {{DISPLAYTITLE:_MOUSEHIDE}} -The '''_MOUSEHIDE''' statement hides the mouse cursor. +The [[_MOUSEHIDE]] statement hides the mouse cursor. {{PageSyntax}} -::: [[_MOUSEHIDE]] - - -''Usage:'' -* Simply call the sub wherever necessary. -* Since the mouse pointer does not interfere with screen changes in '''QB64''', there is little use in hiding the pointer. -* QB64 can even use [[PSET]] and [[POINT]] without hiding the mouse pointer. -* _MOUSEHIDE statements do not accumulate like they did with [[ABSOLUTE]] or [[INTERRUPT]] in Qbasic. +: [[_MOUSEHIDE]] {{PageSeeAlso}} diff --git a/internal/help/_MOUSEINPUT.txt b/internal/help/_MOUSEINPUT.txt index 7fe1df150..8cfa35477 100644 --- a/internal/help/_MOUSEINPUT.txt +++ b/internal/help/_MOUSEINPUT.txt @@ -1,18 +1,19 @@ {{DISPLAYTITLE:_MOUSEINPUT}} -The '''_MOUSEINPUT''' function MUST be used to monitor any new mouse positions, button presses or movements of the scroll wheel. +The [[_MOUSEINPUT]] function is used to monitor any new mouse positions, button presses or movements of the scroll wheel. Must be called before other mouse information becomes available. {{PageSyntax}} -:{{Parameter|infoexist}} = '''_MOUSEINPUT''' +:{{Parameter|infoExists%%}} = [[_MOUSEINPUT]] -''Usage:'' +{{PageDescription}} * Returns -1 if new mouse information is available, otherwise it returns 0. -* MUST be called to read ANY of the other mouse functions! The function will not miss any mouse input even during an [[INPUT]] entry. +* Must be called before reading any of the other mouse functions. The function will not miss any mouse input even during an [[INPUT]] entry. * Use in a loop to monitor the mouse buttons, scroll wheel and coordinate positions. * To clear all previous mouse data, use [[_MOUSEINPUT]] in a loop until it returns 0. +{{PageExamples}} ''Example 1:'' Mouse coordinate, click and scroll events are returned sequentially inside of a _MOUSEINPUT loop. {{CodeStart}} '' '' DO @@ -80,7 +81,7 @@ count = 0 {{PageSeeAlso}} * [[_MOUSEX]], [[_MOUSEY]], [[_MOUSEBUTTON]], [[_MOUSEWHEEL]] * [[_MOUSESHOW]], [[_MOUSEHIDE]], [[_MOUSEMOVE]] -* [[Controller_Devices]] +* [[Controller Devices]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSEMOVE.txt b/internal/help/_MOUSEMOVE.txt index e1699c886..b9ff148e5 100644 --- a/internal/help/_MOUSEMOVE.txt +++ b/internal/help/_MOUSEMOVE.txt @@ -1,23 +1,29 @@ {{DISPLAYTITLE:_MOUSEMOVE}} -The '''_MOUSEMOVE''' statement moves the mouse pointer to a new position on the screen as determined by the column and row coordinates. +The [[_MOUSEMOVE]] statement moves the mouse pointer to a new position on the screen as determined by the column and row coordinates. {{PageSyntax}} -:::'''_MOUSEMOVE''' ''column%'', ''row%'' +:[[_MOUSEMOVE]] {{Parameter|column%}}, {{Parameter|row%}} {{Parameters}} -* [[INTEGER]] ''column'' is the horizontal pixel coordinate to place the mouse pointer and can be any value from 0 to [[_WIDTH (function)|_WIDTH]](0) - 1. -* [[INTEGER]] ''row'' is the vertical pixel position to place the mouse pointer and can be any value from 0 to [[_HEIGHT]](0) - 1 +* {{Parameter|column%}} is the horizontal pixel coordinate to place the mouse pointer and can be any value from 0 to [[_WIDTH (function)|_WIDTH]](0) - 1. +* {{Parameter|row%}} is the vertical pixel position to place the mouse pointer and can be any value from 0 to [[_HEIGHT]](0) - 1 {{PageDescription}} * Maximum coordinate values are based on a program's current [[SCREEN]] mode resolution or the pixel size set by [[_NEWIMAGE]]. -* [[SCREEN]] 0 uses text block coordinates. '''Coordinates off of the screen will create an "Illegal Function Call" [[ERROR Codes|ERROR]]!''' +* [[SCREEN]] 0 uses text block coordinates. '''Coordinates off the screen area will create an "Illegal Function Call" [[ERROR Codes|ERROR]]''' * Can be used to position the pointer to a default dialog button or move the cursor away from a button so it is not clicked twice. -* Does NOT require [[_MOUSEINPUT]] to be used, but all moves will be remembered and can be read by mouse functions. +* Does not require [[_MOUSEINPUT]] to be used, but all moves will be remembered and can be read by mouse functions. +==Availability== +* '''Versions prior to 1.000''' (Version 1.000 had this function disabled for compatibility reasons.) +* '''Version 1.1 and up''' + + +{{PageExamples}} ''Example:'' How to move the mouse cursor using remembered mouse movements. Press any key to quit. {{CodeStart}} {{Cl|SCREEN}} 12 @@ -41,10 +47,9 @@ DO: {{Cl|_LIMIT}} 30 : It is recommended that a [[WHILE]] [[_MOUSEINPUT]]: [[WEND]] loop be used immediately after to clear stored mouse events. -''See also:'' +{{PageSeeAlso}} * [[_MOUSEX]], [[_MOUSEY]] * [[_NEWIMAGE]], [[_SCREENIMAGE]] -* [[DECLARE LIBRARY|MouseMove]] {{text|(SDL Library Function)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSEMOVEMENTX.txt b/internal/help/_MOUSEMOVEMENTX.txt index 651c96955..617d7d96e 100644 --- a/internal/help/_MOUSEMOVEMENTX.txt +++ b/internal/help/_MOUSEMOVEMENTX.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_MOUSEMOVEMENTX}} -The '''_MOUSEMOVEMENTX''' function returns the relative horizontal position of the mouse cursor as positive or negative values. +The [[_MOUSEMOVEMENTX]] function returns the relative horizontal position of the mouse cursor as positive or negative values. {{PageSyntax}} -::: verticalmove = '''_MOUSEMOVEMENTY''' +: ''horizontalMove'' = [[_MOUSEMOVEMENTY]] * Returns the relative horizontal cursor pixel position compared to the previous cursor position. Negative values are moves to the left. -* '''Hides the mouse cursor''' once it is inside of the program window area. This may lead to some ''"confusion"'' by the user! * '''Note:''' A [[_MOUSESHOW]] statement will disable [[_MOUSEMOVEMENTX]] or [[_MOUSEMOVEMENTY]] relative mouse movement reads. * Can also be used to check for any mouse movements to enable a program or close [[Screen Saver Programs]]. * Sets the mouse to a relative movement mode which can be read by [[_WHEEL]] instead of [[_AXIS]] as mouse [[_DEVICES|device]] 2. +{{PageExamples}} ''Example 1:'' Since values returned are relative to the last position, the returns can be positive or negative. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 @@ -44,10 +44,10 @@ PX = 320: PY = 240 'center position {{Cl|PCOPY}} 1, 0 {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" 'press any key to exit '' '' {{CodeEnd}} -: '''NOTE: '''When using the function this way, give the user a keypress exit option! Make sure the user has some way to exit that is not dependent on clicking the X button! +: '''NOTE:''' When using the function this way, give the user a keypress exit option. Make sure the user has some way to exit that is not dependent on clicking the X button. -''See also:'' +{{PageSeeAlso}} * [[_MOUSEMOVEMENTY]] * [[_MOUSEINPUT]], [[_MOUSEX]] * [[_DEVICES]], [[_DEVICEINPUT]] diff --git a/internal/help/_MOUSEMOVEMENTY.txt b/internal/help/_MOUSEMOVEMENTY.txt index 25ae68bdd..4b5082481 100644 --- a/internal/help/_MOUSEMOVEMENTY.txt +++ b/internal/help/_MOUSEMOVEMENTY.txt @@ -1,13 +1,12 @@ {{DISPLAYTITLE:_MOUSEMOVEMENTY}} -The '''_MOUSEMOVEMENTY''' function returns the relative vertical position of the mouse cursor as positive or negative values. +The [[_MOUSEMOVEMENTY]] function returns the relative vertical position of the mouse cursor as positive or negative values. {{PageSyntax}} -::: verticalmove = '''_MOUSEMOVEMENTY''' +: {{Parameter|verticalMove}} = [[_MOUSEMOVEMENTY]] * Returns the relative vertical cursor pixel position compared to the previous cursor position. Negative values are up moves. -* '''Hides the mouse cursor''' once inside the program window area. This may lead to some ''"confusion"'' by the user! * '''Note:''' A [[_MOUSESHOW]] statement will disable [[_MOUSEMOVEMENTX]] or [[_MOUSEMOVEMENTY]] relative mouse movement reads. * Can also be used to check for any mouse movements to enable a program or close [[Screen Saver Programs]]. * Sets the mouse to a relative movement mode which can be read by [[_WHEEL]] instead of [[_AXIS]] as mouse [[_DEVICES|device]] 2. @@ -28,11 +27,11 @@ The '''_MOUSEMOVEMENTY''' function returns the relative vertical position of the {{Cl|PCOPY}} 1, 0 {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} <> "" 'press any key to exit '' '' {{CodeEnd}} -: '''NOTE:''' When using the function this way, give the user a keypress exit option! Make sure the user has some way to exit that is not dependent on clicking the X button. +: '''NOTE:''' When using the function this way, give the user a keypress exit option. Make sure the user has some way to exit that is not dependent on clicking the X button. -''See also:'' -* [[_MOUSEMOVEMENTY]] +{{PageSeeAlso}} +* [[_MOUSEMOVEMENTX]] * [[_MOUSEINPUT]], [[_MOUSEX]] * [[_DEVICES]], [[_DEVICEINPUT]] * [[_WHEEL]], [[_LASTWHEEL]] diff --git a/internal/help/_MOUSEPIPEOPEN.txt b/internal/help/_MOUSEPIPEOPEN.txt index e573ed1bc..0097e3b89 100644 --- a/internal/help/_MOUSEPIPEOPEN.txt +++ b/internal/help/_MOUSEPIPEOPEN.txt @@ -1,15 +1,18 @@ -The '''_MOUSEPIPEOPEN''' function creates a pipe handle value for a mouse when using a virtual keyboard. +{{DISPLAYTITLE: _MOUSEPIPEOPEN}} + +The [[_MOUSEPIPEOPEN]] function creates a pipe handle value for a mouse when using a virtual keyboard. {{PageSyntax}} -::: VkMousePipe = '''_MOUSEPIPEOPEN''' +: vkMousePipe = [[_MOUSEPIPEOPEN]] {{PageDescription}} * The pipe handle value can be used optionally with [[_MOUSEINPUT]], [[_MOUSEX]], [[_MOUSEY]], and [[_MOUSEBUTTON]] when required. -''Example:'' Here's how it looks in my program...(warning: completely useless code snippet) +{{PageExamples}} +''Snippet:'' The following snippet isn't runnable/compilable, but it showcases the use of the [[_MOUSEPIPEOPEN]] function. {{CodeStart}} mDown = 0 mUp = 0 @@ -88,12 +91,12 @@ The '''_MOUSEPIPEOPEN''' function creates a pipe handle value for a mouse when u IF VkMousePipeCapture = 0 THEN {{Cl|_MOUSEINPUTPIPE}} VkMousePipe {{Cl|END}} I -{{CodeEnd}} -: When I'm using the virtual keyboard the keyboard captures mouse input appropriately whilst selectively letting presses originating on non-key areas of the screen filter through to the default mouse queue. +{{TextEnd}} +: When using the [[$VIRTUALKEYBOARD|virtual keyboard]], the keyboard captures mouse input appropriately whilst selectively letting presses originating on non-key areas of the screen filter through to the default mouse queue. -''See Also:'' - +{{PageSeeAlso}} +* [[$VIRTUALKEYBOARD]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSESHOW.txt b/internal/help/_MOUSESHOW.txt index 1c5548934..ba7064d8a 100644 --- a/internal/help/_MOUSESHOW.txt +++ b/internal/help/_MOUSESHOW.txt @@ -1,14 +1,14 @@ {{DISPLAYTITLE:_MOUSESHOW}} -The '''_MOUSESHOW''' statement displays the mouse cursor and can determine its shape in GL. +The [[_MOUSESHOW]] statement displays the mouse cursor and can change its shape. {{PageSyntax}} -::: '''_MOUSESHOW''' [''cursortype$''] +: [[_MOUSESHOW]] [{{Parameter|cursorShape$}}] -''Description:'' +{{PageDescription}} * Simply use the statement whenever [[_MOUSEHIDE]] has been used previously. -* In '''QB64 GL''' the following [[STRING]] cursor types can be displayed: +* In '''version 1.000 and up''' the following {{Parameter|cursorShape$}} can be displayed: ::_MOUSESHOW "LINK" will display an upward pointing hand cursor used to denote hypertext ::_MOUSESHOW "TEXT" will display the I cursor often used in text entry areas ::_MOUSESHOW "CROSSHAIR" will display a crosshair cursor @@ -19,24 +19,23 @@ The '''_MOUSESHOW''' statement displays the mouse cursor and can determine its s ::_MOUSESHOW "DEFAULT" can be used after a mouse cursor statement above was previously used. * This statement will also disable [[_MOUSEMOVEMENTX]] or [[_MOUSEMOVEMENTY]] relative mouse movement reads. * The mouse cursor will not interfere with any print or graphic screen changes in '''QB64'''. -* _MOUSEHIDE statements do not accumulate like they did with [[ABSOLUTE]] or [[INTERRUPT]] in Qbasic. -''Example 1:'' '''QB64 GL''' allows special cursors to be displayed by using special string parameters: -{{CodeStart}} '' '' -User32 "default": {{Cl|_DELAY}} 0.5 -User32 "link": {{Cl|_DELAY}} 0.5 'a hand, typically used in web browsers -User32 "text": {{Cl|_DELAY}} 0.5 -User32 "crosshair": {{Cl|_DELAY}} 0.5 -User32 "vertical": {{Cl|_DELAY}} 0.5 -User32 "horizontal": {{Cl|_DELAY}} 0.5 -User32 "topleft_bottomright": {{Cl|_DELAY}} 0.5 -User32 "topright_bottomleft": {{Cl|_DELAY}} 0.5 -{{Cl|END}} +===QBasic/QuickBASIC=== +* _MOUSEHIDE statements do not accumulate like they did with [[ABSOLUTE]] or [[INTERRUPT]] in QBasic. -SUB User32 (c$) -{{Cl|_MOUSESHOW}} c$ -END SUB'' '' + +{{PageExamples}} +''Example 1:'' '''QB64 1.000 and up''' allow special cursors to be displayed by using special string parameters: +{{CodeStart}} +{{Cl|_MOUSESHOW}} "default": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "link": {{Cl|_DELAY}} 0.5 'a hand, typically used in web browsers +{{Cl|_MOUSESHOW}} "text": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "crosshair": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "vertical": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "horizontal": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "topleft_bottomright": {{Cl|_DELAY}} 0.5 +{{Cl|_MOUSESHOW}} "topright_bottomleft": {{Cl|_DELAY}} 0.5 {{CodeEnd}} : '''Note:''' There is no hourglass, stopwatch or spinning colorful wheel in the list. The fact is that these typically only appear in a program when something has gone terribly wrong and the program has crashed or frozen. diff --git a/internal/help/_MOUSEWHEEL.txt b/internal/help/_MOUSEWHEEL.txt index 57c09c2d7..e264f4e77 100644 --- a/internal/help/_MOUSEWHEEL.txt +++ b/internal/help/_MOUSEWHEEL.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_MOUSEWHEEL}} -The '''_MOUSEWHEEL''' function returns a positive or negative [[INTEGER]] value indicating mouse scroll clicks since the last read. +The [[_MOUSEWHEEL]] function returns a positive or negative [[INTEGER]] value indicating mouse scroll events since the last read of [[_MOUSEINPUT]]. {{PageSyntax}} -::: scroll% = '''_MOUSEWHEEL''' +: {{Parameter|scrollAmount%}} = [[_MOUSEWHEEL]] -''Usage:'' -* A return value of 1 represent one "click" the mouse scroll wheel was moved toward the user. -* A return value of -1 represent one "click" the mouse scroll wheel was moved away from the user. -* After a "click" has been read, the value resets to 0 automatically so cumulative position values must be added. -* If no movement on the wheel has occurred since the last [[_MOUSEINPUT]] read, _MOUSEWHEEL returns 0. +{{PageDescription}} +* Returns -1 when scrolling up and 1 when scrolling down with 0 indicating no movement since last read. +* After an event has been read, the value resets to 0 automatically so cumulative position values must be added. +* If no movement on the wheel has occurred since the last [[_MOUSEINPUT]] read, [[_MOUSEWHEEL]] returns 0. +{{PageExamples}} ''Example 1:'' Reading the cumulative mouse wheel "clicks". {{CodeStart}} '' '' DO: {{Cl|_LIMIT}} 100 @@ -53,14 +53,14 @@ DO {{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|INKEY$}} > "" '' '' {{CodeEnd}} {{small|Code by Ted Weissgerber}} -<center>Note: QB64 comes with a text file called ''readme.txt'' that is large enough for this example.</center> +<center>Note: You will need a text file that is large enough for this example.</center> {{PageSeeAlso}} * [[_MOUSEX]], [[_MOUSEY]], [[_MOUSEBUTTON]] * [[_MOUSEINPUT]], [[_MOUSEMOVE]] * [[_MOUSESHOW]], [[_MOUSEHIDE]] -* [[Controller_Devices]] +* [[Controller Devices]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSEX.txt b/internal/help/_MOUSEX.txt index b3c318573..93194d5cd 100644 --- a/internal/help/_MOUSEX.txt +++ b/internal/help/_MOUSEX.txt @@ -1,20 +1,24 @@ {{DISPLAYTITLE:_MOUSEX}} -The '''_MOUSEX''' function returns the current horizontal(column) mouse cursor position when read after [[_MOUSEINPUT]]. +The [[_MOUSEX]] function returns the current horizontal (column) mouse cursor position when read after [[_MOUSEINPUT]]. {{PageSyntax}} -::: pixelcolumn% = '''_MOUSEX''' +: {{Parameter|pixelColumn%}} = [[_MOUSEX]] -''Usage:'' -* [[SCREEN]] 0 returns the [[SINGLE]] horizontal text column position. Use [[INTEGER]] variables to avoid floating decimal returns. +{{PageDescription}} +* [[SCREEN]] 0 returns the [[INTEGER]] horizontal text column position (from build 20170817/62 onward); older versions return a [[SINGLE]] horizontal text column position. Use [[INTEGER]] variables to avoid floating decimal returns. * Graphic screen modes 1, 2 and 7 to 13 and [[_NEWIMAGE]] 32 bit return the [[INTEGER]] pixel columns. * To calculate text columns in graphic modes, divide the return by 8 or the [[_FONTWIDTH]] of [[_FONT]] characters. -* [[_MOUSEINPUT]] MUST be used to detect any changes in the mouse position and is '''required''' for any coordinate returns. -* '''Note:''' In [[SCREEN]] 0, Qbasic's [[ABSOLUTE]] returned graphic coordinates. QB64 mouse functions return the text coordinates. +* [[_MOUSEINPUT]] must be used to detect any changes in the mouse position and is '''required''' for any coordinate returns. -''Example:'' A simple mouse drawing board using _MOUSEX and [[_MOUSEY]] coordinate values. +==QBasic/QuickBASIC== +* In [[SCREEN]] 0, QBasic's [[ABSOLUTE]] returned graphic coordinates. QB64 mouse functions return the text coordinates. + + +{{PageExamples}} +''Example:'' A simple mouse drawing board using [[_MOUSEX]] and [[_MOUSEY]] coordinate values. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 12 {{Cl|LINE}} (99, 9)-(601, 401), 7, BF @@ -39,10 +43,12 @@ tm$ = " Column = ### Row = ### Button1 = ## Button2 = ## Button3 = ##&q {{PageSeeAlso}} -* [[_MOUSEY]], [[_MOUSEBUTTON]], [[_MOUSEWHEEL]] +* [[_MOUSEY]] +* [[_MOUSEBUTTON]], [[_MOUSEWHEEL]] * [[_MOUSEINPUT]], [[_MOUSEMOVE]] * [[_MOUSESHOW]], [[_MOUSEHIDE]] -* [[Controller_Devices]] +* [[_MOUSEMOVEMENTX]], [[_MOUSEMOVEMENTY]] {{text|(relative pointer moves)}} +* [[Controller Devices]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_MOUSEY.txt b/internal/help/_MOUSEY.txt index 6be56e525..46c5e5de3 100644 --- a/internal/help/_MOUSEY.txt +++ b/internal/help/_MOUSEY.txt @@ -1,19 +1,23 @@ {{DISPLAYTITLE:_MOUSEY}} -'''_MOUSEY''' Function returns the current vertical(row) mouse cursor position when read after [[_MOUSEINPUT]]. +The [[_MOUSEY]] function returns the current vertical (row) mouse cursor position when read after [[_MOUSEINPUT]]. {{PageSyntax}} -::: pixelrow% = [[_MOUSEY]] +: {{Parameter|pixelRow%}} = [[_MOUSEY]] -''Usage:'' -* [[SCREEN]] 0 returns the [[SINGLE]] horizontal text row position. Use [[INTEGER]] variables to avoid floating decimal returns. +{{PageDescription}} +* [[SCREEN]] 0 returns the [[INTEGER]] vertical text row position (from build 20170817/62 onward); older versions return a [[SINGLE]] vertical text row position. Use [[INTEGER]] variables to avoid floating decimal returns. * Graphic screen modes 1, 2 and 7 to 13 and [[_NEWIMAGE]] 32 bit return the [[INTEGER]] pixel columns. * To calculate text rows in graphic modes divide the return by 16 or the [[_FONTHEIGHT]] of [[_FONT]] characters. -* [[_MOUSEINPUT]] MUST be used to detect any changes in the mouse position and is '''required''' for any coordinate returns. -* '''Note:''' In [[SCREEN]] 0, Qbasic's [[ABSOLUTE]] returned graphic coordinates. QB64 mouse functions return the text coordinates. +* [[_MOUSEINPUT]] must be used to detect any changes in the mouse position and is '''required''' for any coordinate returns. +==QBasic/QuickBASIC== +* In [[SCREEN]] 0, QBasic's [[ABSOLUTE]] returned graphic coordinates. QB64 mouse functions return the text coordinates. + + +{{PageExamples}} ''Example:'' Highlighting a row of text in Screen 0. {{CodeStart}} '' '' minX = 20: maxX = 60: minY = 10: maxY = 24 @@ -23,8 +27,8 @@ selection = 0 'the screen Y coordinate of the previously highlighted item {{Cl|IF}} {{Cl|_MOUSEINPUT}} {{Cl|THEN}} 'Un-highlight any selected row {{Cl|IF}} selection {{Cl|THEN}} selectRow selection, minX, maxX, 0 - x = {{Cl|CINT}}({{Cl|_MOUSEX}}) - y = {{Cl|CINT}}({{Cl|_MOUSEY}}) + x = {{Cl|_MOUSEX}} + y = {{Cl|_MOUSEY}} {{Cl|IF}} x >= minX {{Cl|AND (boolean)|AND}} x <= maxX {{Cl|AND (boolean)|AND}} y >= minY {{Cl|AND (boolean)|AND}} y <= maxY {{Cl|THEN}} selection = y {{Cl|ELSE}} @@ -52,7 +56,8 @@ addr& = (x1 - 1 + (y - 1) * {{Cl|_WIDTH (function)|_WIDTH}}) * 2 + 1 * [[_MOUSEX]], [[_MOUSEBUTTON]], [[_MOUSEWHEEL]] * [[_MOUSEINPUT]], [[_MOUSEMOVE]] * [[_MOUSESHOW]], [[_MOUSEHIDE]] -* [[Controller_Devices]] +* [[_MOUSEMOVEMENTX]], [[_MOUSEMOVEMENTY]] {{text|(relative pointer moves)}} +* [[Controller Devices]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_NEWIMAGE.txt b/internal/help/_NEWIMAGE.txt index 327c88e30..36d79f0fb 100644 --- a/internal/help/_NEWIMAGE.txt +++ b/internal/help/_NEWIMAGE.txt @@ -1,30 +1,32 @@ {{DISPLAYTITLE:_NEWIMAGE}} -The '''_NEWIMAGE''' function prepares a window image surface and returns the [[LONG]] [[handle]] value. +The [[_NEWIMAGE]] function prepares a window image surface and returns the [[LONG]] [[handle]] value. {{PageSyntax}} -: handle& = '''_NEWIMAGE ('''''width&'', ''height&''[, {''0''|''1''|''2''|''7''|''8''|''9''|''10''|''11''|''12''|''13''|''256''|''32''}]''')''' +: {{Parameter|handle&}} = [[_NEWIMAGE]]({{Parameter|width&}}, {{Parameter|height&}}[, {''0''|''1''|''2''|''7''|''8''|''9''|''10''|''11''|''12''|''13''|''256''|''32''}]) {{Parameters}} -* Minimum [[LONG]] screen dimensions are ''width'' >= 1, ''height'' >= 1 measured in pixels as [[INTEGER]] or [[LONG]] values. -* Mode is either a QB type [[SCREEN|screen]] mode(0 to 2 or 7 to 13) or 256 colors or 32 bit(16 million colors) compatible. +* Minimum [[LONG]] screen dimensions are {{Parameter|width&}} >= 1, {{Parameter|height&}} >= 1 measured in pixels as [[INTEGER]] or [[LONG]] values. +** For mode 0 (text), {{Parameter|width&}} and {{Parameter|height&}} are measured in character blocks, not pixels. +* Mode is either a QBasic type [[SCREEN|screen]] mode (0 to 2 or 7 to 13), 256 colors or 32 bit (16 million colors) compatible. -''Usage:'' -* If the mode is omitted, an image will be created with the same BPP mode, font(which may block freeing of that font), palette, selected colors, transparent color, blend state and print method settings as the current destination image/[[SCREEN|screen]] page. +{{PageDescription}} +* If the mode is omitted, an image will be created with the same BPP mode, font (which may block freeing of that font), palette, selected colors, transparent color, blend state and print method settings as the current [[_DEST]]ination image/[[SCREEN|screen]] page. * Valid [[LONG]] [[handle]] returns are less than -1. Invalid handles equal -1 and a zero or positive value is also invalid. -* You can create any sized window(limited by the OS) in any emulated [[SCREEN]] mode or 32 bit using this function. +* You can create any sized window (limited by the OS) in any emulated [[SCREEN]] mode or 32 bit using this function. * Default text block size in emulated [[SCREEN]] modes 1, 2, 7, 8 and 13 is 8 X 8; 9 and 10 is 8 X 14; 11, 12, 256 and 32 bit is 8 X 16. The text block pixel size will allow you to calculate the available text rows and columns in a custom sized screen. -* To view the image page, just use [[SCREEN]] handle&. Even if another procedure changes the screen mode and clears the screen, the image can be restored later by using the same SCREEN handle mode. -* Use the {{KW|_COPYIMAGE}} function to preserve a SCREEN handle value when changing to another screen mode to restore it later. -* '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' +* To view the image page, just use [[SCREEN]] {{Parameter|handle&}}. Even if another procedure changes the screen mode and clears the screen, the image can be restored later by using the same SCREEN handle mode. +* Use the [[_COPYIMAGE]] function to preserve a SCREEN handle value when changing to another screen mode to restore it later. +* '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] so that they are transparent when placed over other surfaces.''' : Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opague. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' -* '''It is IMPORTANT to free unused or uneeded images with [[_FREEIMAGE]] to prevent CPU [[ERROR_Codes#Other_Errors|memory overflow errors]]!''' -* '''Do NOT try to free image handles currently being used as the active [[SCREEN]]! Change screen modes first.''' +* '''It is important to free unused or uneeded images with [[_FREEIMAGE]] to prevent CPU [[ERROR_Codes#Other_Errors|memory overflow errors]].''' +* '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.''' +{{PageExamples}} ''Example 1:'' Shrinking a SCREEN 0 text window's size: {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(28, 25, 0) '' '' @@ -77,16 +79,13 @@ mode2& = {{Cl|_NEWIMAGE}} (300, 200, 13) {{CodeEnd}} :''Explanation:'' The [[_DEST (function)|_DEST]] function can determine the present screen mode destination handle. The second _NEWIMAGE handle is created using a SCREEN 13 palette(256 colors also). Each SCREEN is worked on after changing the destination with [[_DEST]] ''handle&'' statement. Images can be created before viewing them. When a key is pressed the second SCREEN created is displayed and so on. -:'''Legacy SCREEN modes can also return a _DEST value, but the value will create a handle error!''' To restore legacy screens get the[[_COPYIMAGE]] function value before changing screens. Then restore it using SCREEN oldmode&. +:'''Legacy SCREEN modes can also return a _DEST value, but the value will create a handle error.''' To restore legacy screens get the[[_COPYIMAGE]] function value before changing screens. Then restore it using SCREEN oldmode&. -''See Examples:'' - -[[SAVEIMAGE]] (Bitmap creation) - -[[_FILE$]] (restoring previous screen) - -[[_PIXELSIZE]] (GetImage function example) +===More examples=== +* [[SAVEIMAGE]] (Bitmap creation) +* [[_FILE$]] (restoring previous screen) +* [[_PIXELSIZE]] (GetImage function example) {{PageSeeAlso}} @@ -95,9 +94,8 @@ mode2& = {{Cl|_NEWIMAGE}} (300, 200, 13) * [[_FREEIMAGE]] * [[_PUTIMAGE]] * [[_SCREENIMAGE]] +* [[_CLIPBOARDIMAGE (function)]] * [[SCREEN]] - - {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_OFFSET.txt b/internal/help/_OFFSET.txt index bda08ed75..b7ac28824 100644 --- a/internal/help/_OFFSET.txt +++ b/internal/help/_OFFSET.txt @@ -1,21 +1,22 @@ {{DISPLAYTITLE:_OFFSET}} -The '''_OFFSET''' variable type stores the location of a value in memory. The byte size varies as required by the system. +The [[_OFFSET]] variable type stores the location of a value in memory. The byte size varies as required by the system. {{PageSyntax}} -::: [[DIM]] variable [[AS]] '''_OFFSET''' +: [[DIM]] variable [[AS]] '''_OFFSET''' -''Usage:'' +{{PageDescription}} * _OFFSET types can be created as signed or [[_UNSIGNED]] at the programmer's discretion. * The type suffix for _OFFSET is '''%&''' which designates the integer value's flexible size. -* Offset values are currently only useful when used in conjunction with [[_MEM]] or [[DECLARE LIBRARY]] procedures. +* Offset values are only useful when used in conjunction with [[_MEM]] or [[DECLARE LIBRARY]] procedures. * OFFSET values are used as a part of the [[_MEM]] variable [[type]] in QB64. Variable.OFFSET returns or sets the current position in memory. * API [[DECLARE LIBRARY|LIBRARY]] parameter or [[TYPE|type]] names may include '''lp, ptr''' or '''p''' which designates them as a pointer type. -* '''Warning: _OFFSET values cannot be cast to other variable type values reliably!''' -* '''Warning: Variable length [[STRING]] values can move about in memory AT ANY TIME!''' If you get the _OFFSET of a variable length sting on one code line and use it on the next it may not be there anymore. '''To be safe, move variable length strings into fixed length strings first.''' +* '''Warning: _OFFSET values cannot be cast to other variable type values reliably.''' +* '''Warning: Variable length [[STRING]] values can move about in memory at any time.''' If you get the _OFFSET of a variable length sting on one code line and use it on the next it may not be there anymore.''' To be safe, move variable length strings into fixed length strings first.''' +{{PageExamples}} ''Example:'' The SHBrowseForFolder function receives information about the folder selected by the user in Windows XP and 7. {{CodeStart}} '' '' {{Cl|DECLARE DYNAMIC LIBRARY|DECLARE CUSTOMTYPE LIBRARY}} @@ -61,7 +62,7 @@ o = SHBrowseForFolder(b) {{small|Code by Galleon}} -''See also:'' +{{PageSeeAlso}} * [[Using _OFFSET]] * [[_OFFSET (function)]], [[_MEM]] * [[DECLARE LIBRARY]] diff --git a/internal/help/_OFFSET_(function).txt b/internal/help/_OFFSET_(function).txt index 29df97cd6..844470d0a 100644 --- a/internal/help/_OFFSET_(function).txt +++ b/internal/help/_OFFSET_(function).txt @@ -1,21 +1,22 @@ {{DISPLAYTITLE:_OFFSET (function)}} -The '''_OFFSET''' function returns the memory offset of/within a given variable. +The [[_OFFSET]] function returns the memory offset of/within a given variable. {{PageSyntax}} - -::: offset%& = '''_OFFSET('''''variable''''')''' +: {{Parameter|offset%&}} = [[_OFFSET]]({{Parameter|variable}}) -* The ''variable'' parameter can be any type of numerical or [[STRING|string]] variable name. -* Application parameter or [[TYPE|type]] names may include lp, ptr or p which designates them as a pointer type. +{{PageDescription}} +* The {{Parameter|variable}} parameter can be any type of numerical or [[STRING|string]] variable name. +* API [[DECLARE LIBRARY|LIBRARY]] parameter or [[TYPE|type]] names may include '''lp, ptr''' or '''p''' which designates them as a pointer type. * _OFFSET function return values should be stored in [[_OFFSET]] type variables. As no other variable type is 'elastic' like [[_OFFSET]], there can be no guarantee that any other variable type can hold the value of an _OFFSET. * Returns the memory offset of variables, user-defined-types & elements, arrays & indices and the base offset of [[STRING]]s. * Offset values are currently only useful when used in conjunction with [[_MEM]] or [[DECLARE LIBRARY]] procedures. -* OFFSET values are used as a part of the [[_MEM]] variable [[type]] in QB64. Variable.OFFSET returns or sets the current position in memory. -* '''Warning:''' QB64 variable length strings can move about in memory AT ANY TIME. If you get the _OFFSET of a variable length sting on one line and use it on the next it may not be there anymore. '''To be safe, move variable length strings into fixed length strings first.''' +* OFFSET values are used as a part of the [[_MEM]] variable [[type]] in QB64; {{Parameter|variable}}.OFFSET returns or sets the current position in memory. +* '''Warning:''' QB64 variable length strings can move about in memory at any time. If you get the _OFFSET of a variable length sting on one line and use it on the next it may not be there anymore.''' To be safe, move variable length strings into fixed length strings first.''' +{{PageExamples}} ''Example:'' Using memcpy with the _OFFSET function values as parameters. {{CodeStart}} '' '' {{Cl|DECLARE DYNAMIC LIBRARY|DECLARE CUSTOMTYPE LIBRARY}} @@ -32,7 +33,7 @@ memcpy {{Cl|_OFFSET (function)|_OFFSET}}(a$) + 5, {{Cl|_OFFSET (function)|_OFFSE {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_OFFSET]] {{text|(variable type)}} * [[DECLARE LIBRARY]] * [[DECLARE DYNAMIC LIBRARY]] diff --git a/internal/help/_OPENCLIENT.txt b/internal/help/_OPENCLIENT.txt index af49e9116..fd45373b0 100644 --- a/internal/help/_OPENCLIENT.txt +++ b/internal/help/_OPENCLIENT.txt @@ -3,15 +3,15 @@ The [[_OPENCLIENT]] function connects to a Host on the Internet as a Client and {{PageSyntax}} -::: client_handle = '''_OPENCLIENT('''"TCP/IP:8080:12:30:1:10"''')''' +: {{Parameter|clientHandle&}} = [[_OPENCLIENT]]('''"TCP/IP:8080:12:30:1:10"''') {{PageDescription}} -* [[ERROR Codes|ILLEGAL FUNCTION CALL]] error if called with a string argument of the wrong syntax. +* An [[ERROR Codes|Illegal Function Call]] error will be triggered if the function is called with a string argument of the wrong syntax. * Connects to a host somewhere on the internet as a client. -* Valid client handles are negative values. 0 means that the connection failed! Always check that the handle returned is NOT 0! -* {{KW|CLOSE}} client_handle closes the client. A failed handle of value 0 does not need to be closed. +* Valid {{Parameter|clientHandle&}} values are negative. 0 means that the connection failed. Always check that the handle returned is not 0. +* [[CLOSE]] client_handle closes the client. A failed handle of value 0 does not need to be closed. {{PageExamples}} diff --git a/internal/help/_OPENCONNECTION.txt b/internal/help/_OPENCONNECTION.txt index 08d992c7e..a1914b061 100644 --- a/internal/help/_OPENCONNECTION.txt +++ b/internal/help/_OPENCONNECTION.txt @@ -1,23 +1,23 @@ {{DISPLAYTITLE:_OPENCONNECTION}} -The '''_OPENCONNECTION''' function open's a connection from a client that the host has detected and returns a status handle. +The [[_OPENCONNECTION]] function opens a connection from a client that the host has detected and returns a status handle. {{PageSyntax}} -:{{Parameter|connect_handle}} = '''_OPENCONNECTION}}('''{{Parameter|host_handle}}''')''' +:{{Parameter|connectHandle}} = [[_OPENCONNECTION]]({{Parameter|hostHandle}}) {{PageDescription}} -* Valid handles returned are usually negative numbers. -* If the syntax is correct but they fail to begin/connect a handle of 0 is returned. +* Valid {{Parameter|connectHandle}} values returned are negative numbers. +* If the syntax is correct but they fail to begin/connect, a {{Parameter|connectHandle}} of 0 is returned. * Always check if the handle returned is 0 (failed) before continuing. -* {{KW|CLOSE}} #{{Parameter|connect_handle}} closes the connection. Failed connections({{Parameter|connect_handle}} = 0) do not need to be closed. -* As a '''Host''' you can check for new clients(users). Each will have a unique connection handle. -* Creates an [[ERROR Codes|ILLEGAL FUNCTION CALL]] error if called with a string argument of the wrong syntax. -* Handle values can be used as the open number by {{KW|INPUT (TCP/IP statement)|INPUT #}} or {{KW|GET (TCP/IP statement)|GET #}} read statements and {{KW|PUT (TCP/IP statement)|PUT #}} or {{KW|PRINT (TCP/IP statement)|PRINT #}} write statements. +* [[CLOSE]] #{{Parameter|connectHandle}} closes the connection. Failed connections({{Parameter|connectHandle}} = 0) do not need to be closed. +* As a '''Host''' you can check for new clients (users). Each will have a unique connection handle. +* Creates an [[ERROR Codes|Illegal Function Call]] error if called with a string argument of the wrong syntax. +* Handle values can be used as the open number by [[INPUT (TCP/IP statement)|INPUT #]] or [[GET (TCP/IP statement)|GET #]] read statements and [[PUT (TCP/IP statement)|PUT #]] or [[PRINT (TCP/IP statement)|PRINT #]] write statements. {{PageExamples}} -''Example:'' Using the {{KW|_OPENCONNECTION}} new client return with {{KW|INPUT (TCP/IP statement)|INPUT}} # or {{KW|GET (TCP/IP statement)|GET}} # message or data reads. +''Example:'' Using the [[_OPENCONNECTION]] new client return with [[INPUT (TCP/IP statement)|INPUT]] # or [[GET (TCP/IP statement)|GET]] # message or data reads. {{CodeStart}} diff --git a/internal/help/_OPENHOST.txt b/internal/help/_OPENHOST.txt index e7240e27f..207f2aecd 100644 --- a/internal/help/_OPENHOST.txt +++ b/internal/help/_OPENHOST.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_OPENHOST}} -The '''_OPENHOST''' function opens a Host which listens for new connections and returns a Host status handle. +The [[_OPENHOST]] function opens a Host which listens for new connections and returns a Host status handle. {{PageSyntax}} -::: host_handle = '''_OPENHOST('''"TCP/IP:8080"''')''' +: {{Parameter|hostHandle}} = [[_OPENHOST]]('''"TCP/IP:8080"''') {{PageDescription}} -* Creates an ILLEGAL FUNCTION CALL if called with a string argument of the wrong syntax. +* Creates an [[ERROR Codes|Illegal Function Call]] error if called with a string argument of the wrong syntax. * The port used in the syntax example is 8080. -* Valid handle values are usually negative number values. -* If the syntax is correct but they fail to begin/connect a handle of 0 is returned. +* Valid {{Parameter|hostHandle}} values are negative numbers. +* If the syntax is correct but they fail to begin/connect a {{Parameter|hostHandle}} of 0 is returned. * Always check if the handle returned is 0 (failed) before continuing. -* {{KW|CLOSE}} {{Parameter|host_handle}} closes the host. A failed handle value of 0 does not need to be closed. +* [[CLOSE]] {{Parameter|hostHandle}} closes the host. A failed handle value of 0 does not need to be closed. {{PageExamples}} @@ -113,7 +113,7 @@ Mini Messenger Enter your name:_ {{OutputEnd}} -''Explanation:'' The SendMessage SUB program controls the program exit unless both Client and Host fail. Entering no message and hitting [Enter] or pressing the [Esc]] key closes the program. Both SUB programs allow a Client or Host to communicate with others simply. {{KW|INPUT (TCP/IP statement)|INPUT #}} is used to read messages and {{KW|PRINT (TCP/IP statement)|PRINT #}} is used to send messages. The client handle value is used as the port number. Keep in mind that this is just an example. A lot could be added like recording IP addresses! +''Explanation:'' The SendMessage SUB program controls the program exit unless both Client and Host fail. Entering no message and hitting [Enter] or pressing the [Esc]] key closes the program. Both SUB programs allow a Client or Host to communicate with others simply. {{KW|INPUT (TCP/IP statement)|INPUT #}} is used to read messages and {{KW|PRINT (TCP/IP statement)|PRINT #}} is used to send messages. The client handle value is used as the port number. Keep in mind that this is just an example. A lot could be added, like recording IP addresses. <center>'''To manage the users array, see the [[_CONNECTED]] page example.'''</center> diff --git a/internal/help/_OS$.txt b/internal/help/_OS$.txt index b0c3204b9..b4c885995 100644 --- a/internal/help/_OS$.txt +++ b/internal/help/_OS$.txt @@ -1,23 +1,21 @@ -The '''_OS$''' function returns the operating system and QB64 compiler bit version used to compile a QB64 program. +The [[_OS$]] function returns the operating system and QB64 compiler bit version used to compile a QB64 program. {{PageSyntax}} -:::: compilerversion$ = '''_OS$''' +: {{Parameter|compilerVersion$}} = [[_OS$]] +{{PageDescription}} +* Returns a [[STRING]] listing the OS as [WINDOWS], [LINUX] or [MACOSX] and the compiler bit format of [32BIT] or [64BIT]. [[Example: {{text|[WINDOWS][32BIT]|green}}]] * Allows a BAS program to be compiled with QB64 in Windows, Linux or MacOSX using different OS or language specifications. -* Use the return to specify the current OS code to use when a BAS program is compiled using another version of the QB64 compiler. -* Returns a [[STRING]] listing the OS as [WINDOWS], [LINUX] or [MACOSX] and the compiler bit format of [32BIT] or [64BIT]. -* Windows can use either a 32(default) or 64 bit compiler. Linux and Mac use 64 bit. '''Example: {{text|[WINDOWS][32BIT]|green}}''' -* Note: It may not be possible to run a QB64 EXE program compiled on another operating system to get an _OS$ return value. +* Use the return {{Parameter|compilerVersion$}} to specify the current OS code to use when a BAS program is compiled using another version of the QB64 compiler. +* Windows can use either a 32 (default) or 64 bit compiler. Linux and Mac use 64 bit by default. * Explanation by Galleon: http://www.qb64.net/forum/index.php?topic=12193.msg105406#msg105406 - - -''See also: +{{PageSeeAlso}} * [[ENVIRON$]] -* [http://www.qb64.net/forum/index.php?topic=12204.0 64 BIT Windows Compiler Installation] +* [[QB64_FAQ#Q:_How_do_I_upgrade_the_32_bit_Windows_version_of_QB64_to_64_bit_functionality.3F|Upgrading QB64 to use a 64-bit compiler in Windows]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_PALETTECOLOR.txt b/internal/help/_PALETTECOLOR.txt index b4ff83651..36c922d41 100644 --- a/internal/help/_PALETTECOLOR.txt +++ b/internal/help/_PALETTECOLOR.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_PALETTECOLOR}} -The _PALETTECOLOR statement sets the color value of a palette entry of an image using 256 color modes or less (4 or 8 BPP). +The [[_PALETTECOLOR]] statement sets the color value of a palette entry of an image using 256 color modes or less (4 or 8 BPP). {{PageSyntax}} -:[[_PALETTECOLOR]] {{Parameter|attribute%}}, {{Parameter|colour&}}[, {{Parameter|Dest_Handle&}}] +:[[_PALETTECOLOR]] {{Parameter|attribute%}}, {{Parameter|newColor&}}[, {{Parameter|destHandle&}}] {{PageDescription}} * The {{Parameter|attribute%}} is the palette index number of the color to set, ranging from 0 to 15 (4 bit) or 0 to 255 (8 bit) color modes. -* The [[LONG]] {{Parameter|colour&}} is the new color value to set using [[_RGB32]] or [[_RGBA32]] values or using [[HEX$ 32 Bit Values]]. -* If {{Parameter|imageHandle&}} is omitted, [[_DEST|destination]] is assumed to be the current write page or screen surface. -* If {{Parameter|index%}} is outside of image or [[SCREEN|screen]] mode attribute range(0 to 15 or 0 to 255), an [[ERROR Codes|illegal function call]] error will occur. -* If {{Parameter|DestHandle&}} does not use a palette, an [[ERROR Codes|illegal function call]] error occurs. '''Will not work in 24/32 bit color palette modes!''' -* If {{Parameter|imageHandle&}} is an invalid handle value, an [[ERROR Codes|invalid handle]] error occurs. +* The [[LONG]] {{Parameter|newColor&}} is the new color value to set using [[_RGB32]] or [[_RGBA32]] values or using [[HEX$ 32 Bit Values]]. +* If {{Parameter|destHandle&}} is omitted, [[_DEST|destination]] is assumed to be the current write page or screen surface. +* If {{Parameter|attribute%}} is outside of image or [[SCREEN|screen]] mode attribute range (0 to 15 or 0 to 255), an [[ERROR Codes|illegal function call]] error will occur. +* If {{Parameter|destHandle&}} does not use a palette, an [[ERROR Codes|illegal function call]] error occurs. '''Will not work in 24/32 bit color palette modes.''' +* If {{Parameter|destHandle&}} is an invalid handle value, an [[ERROR Codes|invalid handle]] error occurs. <center>'''Basic's 16 Default Color Attributes (non-[[DAC]])'''</center> @@ -37,9 +37,10 @@ The _PALETTECOLOR statement sets the color value of a palette entry of an image <center>[http://www.w3schools.com/html/html_colornames.asp HTML Color Table Values and Names] or [http://www.tayloredmktg.com/rgb/#OR Other RGB colors]</center> ::: ''Note:'' '''QB64''' 32 bit color intensity values from 0 to 255 can be found by multiplying above values by 4. -''Summary:'' The red, green, and blue intensity values can be changed using [[OUT]] or [[PALETTE]] statements. Some '''Qbasic''' RGB color attribute values can be changed in [[DAC]] {{KW|SCREEN (statement)|SCREEN}} modes and the [[DAC]] RGB intensity settings may be different. +''Summary:'' The red, green, and blue intensity values can be changed using [[OUT]] or [[PALETTE]] statements. Some '''QBasic''' RGB color attribute values can be changed in [[DAC]] [[SCREEN (statement)|SCREEN]] modes and the [[DAC]] RGB intensity settings may be different. +{{PageExamples}} ''Example:'' Creating custom background colors in SCREEN 0 that follow the text. [[CLS]] makes entire background one color. {{CodeStart}} {{Cl|_PALETTECOLOR}} 1, {{Cl|_RGB32}}(255, 255, 255) ' white. @@ -60,7 +61,7 @@ The _PALETTECOLOR statement sets the color value of a palette entry of an image {{Cl|COLOR}} 2, 6: {{Cl|PRINT}} "ligher red on darker red" '' '' {{CodeEnd}} -: ''Note:'' _PALLETCOLOR expects [[LONG]] [[_RGB32]] or [[_RGBA32]] 32 bit color values, NOT [[_RGB]] or [[_RGBA]] palette attribute values. +: ''Note:'' [[_PALETTECOLOR]] expects [[LONG]] [[_RGB32]] or [[_RGBA32]] 32 bit color values, not [[_RGB]] or [[_RGBA]] palette attribute values. {{PageSeeAlso}} diff --git a/internal/help/_PALETTECOLOR_(function).txt b/internal/help/_PALETTECOLOR_(function).txt index d522ddf2f..6fbfa8767 100644 --- a/internal/help/_PALETTECOLOR_(function).txt +++ b/internal/help/_PALETTECOLOR_(function).txt @@ -1,20 +1,20 @@ {{DISPLAYTITLE:_PALETTECOLOR (function)}} -The [[PALETTECOLOR]] function is used to return the 32 bit attribute color setting of an image or screen page handle's palette. +The [[_PALETTECOLOR (function)|_PALETTECOLOR]] function is used to return the 32 bit attribute color setting of an image or screen page handle's palette. {{PageSyntax}} -: color32value& = '''_PALETTECOLOR('''{{Parameter|attribute_number%}}, {{Parameter|handle&}}''')''' - +: {{Parameter|color32Value&}} = [[_PALETTECOLOR (function)|_PALETTECOLOR]]({{Parameter|attributeNumber%}}, {{Parameter|imgHandle&}}) {{PageDescription}} -* {{Parameter|attribute_number&}} is the color attribute value from 0 to 255 for 1, 4 or 8 bit images. -* {{Parameter|handle&}} is the image handle being read for color data. Zero can be used to read the present screen mode palette. +* {{Parameter|attributeNumber%}} is the color attribute value from 0 to 255 for 1, 4 or 8 bit images. +* {{Parameter|imgHandle&}} is the image handle being read for color data. Zero can be used to read the current screen mode palette. * Returns the 32 bit color value to be used by the 32 bit RGB functions. -* For 32 bit images send the _PALETTECOLOR return value to {{KW|_RED32}}, {{KW|_GREEN32}} and {{KW|_BLUE32}} functions to get the Red, Green, and Blue intensity settings. -* '''Although 32 bit palette values are returned, the function cannot be used with 32 bit images or screen modes!''' +* For 32 bit images send the _PALETTECOLOR return value to [[_RED32]], [[_GREEN32]] and [[_BLUE32]] functions to get the red, green, and blue intensity values. +* '''Although 32 bit palette values are returned, the function cannot be used with 32 bit images or screen modes.''' +{{PageExamples}} ''Example:'' How _PALETTECOLOR works on 32 bit RGB compared to a 4 BPP(SCREEN 12) Qbasic procedure. {{CodeStart}} '' '' SCREEN 12 'can use any Qbasic legacy screen mode diff --git a/internal/help/_PI.txt b/internal/help/_PI.txt index 248fd7de2..d4acb438f 100644 --- a/internal/help/_PI.txt +++ b/internal/help/_PI.txt @@ -1,21 +1,22 @@ {{DISPLAYTITLE: _PI}} -The '''_PI''' [[FUNCTION|function]] returns '''π''' as a [[_FLOAT]] value with an optional multiplier parameter. +The [[_PI]] function returns '''&pi;''' as a [[_FLOAT]] value with an optional multiplier parameter. {{PageSyntax}} -::: circumference = '''_PI'''[(''multiplier'')] +: {{Parameter|circumference}} = [[_PI]][({{Parameter|multiplier}})] {{Parameters}} -* Optional ''multiplier'' (''2 * radius'' in above syntax) allows multiplication of the π value. +* Optional {{Parameter|multiplier}} (''2 * radius'' in above syntax) allows multiplication of the π value. {{PageDescription}} -* Function can be used in '''QB64''' only to supply π or multiples in a program. +* Function can be used in to supply π or multiples in a program. * Accuracy is determined by the return variable type [[AS]] [[SINGLE]], [[DOUBLE]] or [[_FLOAT]]. -* The π value can also be derived using 4 * [[ATN]](1) for a [[SINGLE]] value. +* The &pi; value can also be derived using 4 * [[ATN]](1) for a [[SINGLE]] value. +{{PageExamples}} ''Example:'' Calculating the area of a circle using a [[SINGLE]] variable in this case. {{CodeStart}}radius = 5 circlearea = {{Cl|_PI}}(radius ^ 2) diff --git a/internal/help/_PIXELSIZE.txt b/internal/help/_PIXELSIZE.txt index a717befd6..9ec601a9f 100644 --- a/internal/help/_PIXELSIZE.txt +++ b/internal/help/_PIXELSIZE.txt @@ -1,21 +1,22 @@ {{DISPLAYTITLE:_PIXELSIZE}} -The '''_PIXELSIZE''' function returns the color depth (Bits Per Pixel) of an image as 0 for text, 1 for 1 to 8 BPP or 4 for 32 bit. +The [[_PIXELSIZE]] function returns the color depth (Bits Per Pixel) of an image as 0 for text, 1 for 1 to 8 BPP or 4 for 32 bit. {{PageSyntax}} -:: pixelsize% = '''_PIXELSIZE'''[({{Parameter|imageHandle&}})] +: {{Parameter|pixelSize%}} = [[_PIXELSIZE]][({{Parameter|imageHandle&}})] {{PageDescription}} -* If brackets and {{Parameter|imageHandle&}} are omitted, it is assumed to be the current write page. +* If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page. * Returns: -:: 0 if the image or screen page specified by {{Parameter|imageHandle&}} is in text mode. -:: 1 If the image specified by {{Parameter|imageHandle&}} is in 1(B & W), 4(16 color) or 8(256 color) BPP mode. -:: 4 Image specified is a 24/32-bit compatible mode. Pixels use three bytes, one per Red, Green and Blue color intensity. -* The [[SCREEN]] or [[_NEWIMAGE]] or [[_LOADIMAGE]] color(256 or 32) mode can influence the pixel sizes that can be returned. -* If {{Parameter|imageHandle&}} is an invalid handle, then an [[ERROR Codes|invalid handle]] error is returned. +** 0 if the image or screen page specified by {{Parameter|imageHandle&}} is in text mode. +** 1 if the image specified by {{Parameter|imageHandle&}} is in 1 (B & W), 4 (16 colors) or 8 (256 colors) BPP mode. +** 4 if the image specified is a 24/32-bit compatible mode. Pixels use three bytes, one per red, green and blue color intensity. +* The [[SCREEN]] or [[_NEWIMAGE]] or [[_LOADIMAGE]] color mode (256 or 32) can influence the pixel sizes that can be returned. +* If {{Parameter|imageHandle&}} is an invalid handle, then an [[ERROR Codes|invalid handle]] error occurs. +{{PageExamples}} ''Snippet:'' Saving Images for later program use. Handle values could be saved to an array. {{TextStart}} '' '' @@ -32,7 +33,7 @@ GetImage& = h& {{small|Adapted from code by Galleon}} -''See examples:'' +===More examples=== * [[SAVEIMAGE]] {{text|(SUB to convert image to bitmap)}} * [[SaveIcon32]] {{text|(convert any image to icon)}} * [[ThirtyTwoBit SUB]] {{text|(convert partial image to bitmap)}} diff --git a/internal/help/_PRESERVE.txt b/internal/help/_PRESERVE.txt index 1ce0a64b7..3f84ea681 100644 --- a/internal/help/_PRESERVE.txt +++ b/internal/help/_PRESERVE.txt @@ -1,26 +1,25 @@ {{DISPLAYTITLE:_PRESERVE}} -The [[_PRESERVE]] [[REDIM]] action preserves the current contents of [[$DYNAMIC|dynamic]] [[arrays]], when re-sizing or changing indices. - +The [[_PRESERVE]] [[REDIM]] action preserves the current contents of [[$DYNAMIC|dynamic]] [[arrays]], when resizing or changing indices. {{PageSyntax}} -::: REDIM '''_PRESERVE''' Array(100 [TO 200]) [AS variabletype] +: [[REDIM]] [[_PRESERVE]] array({{Parameter|newLowerIndex&}} [TO {{Parameter|newUpperIndex&}}]) [AS variabletype] {{PageDescription}} -* [[REDIM]] or the [[$DYNAMIC]] metacommand must be used when the array is first created to be able to re-size and preserve! -* If [[_PRESERVE]] is not used, the present contents of the array are cleared by [[REDIM]]! -:* All element values of an array are preserved if the array size is increased. -:* The remaining elements of the array are preserved if the array size is decreased. -:* If the new index range is different from the original, all values will be moved to the new corresponding indices. -* '''REDIM [[_PRESERVE]] cannot change the number of array dimensions, but can change the number of elements''' +* [[REDIM]] or the [[$DYNAMIC]] metacommand must be used when the array is first created to be able to resize and preserve. +* If [[_PRESERVE]] is not used, the current contents of the array are cleared by [[REDIM]]. +** All element values of an array are preserved if the array size is increased. +** The remaining elements of the array are preserved if the array size is decreased. +** If the new index range is different from the original, all values will be moved to the new corresponding indices. +* '''REDIM [[_PRESERVE]] cannot change the number of array dimensions, but can change the number of elements.''' * '''Always use the same array [[TYPE]] suffix ([[AS]] type) or a new array type with the same name may be created.''' -''Errors:'' +{{PageErrors}} * [[SUB]] or [[FUNCTION]] arrays created using [[REDIM]] require that they be recreated to be used after arrays are [[ERASE]]d. -* '''Warning! Do not use negative upper bound array index values as OS access or "Out of Memory" [[ERROR Codes|errors]] will occur!''' -* Use _PRESERVE before [[SHARED]] or an "invalid variable name" error will occur in QB64. +* '''Warning:''' Do not use negative upper array index values as an "Out of Memory" [[ERROR Codes|error]] (or global Operating System errors) will occur.''' +* Use [[_PRESERVE]] before [[SHARED]] or an "invalid variable name" error will occur. {{PageExamples}} diff --git a/internal/help/_PRINTIMAGE.txt b/internal/help/_PRINTIMAGE.txt index 947129a60..7d941097f 100644 --- a/internal/help/_PRINTIMAGE.txt +++ b/internal/help/_PRINTIMAGE.txt @@ -1,19 +1,20 @@ {{DISPLAYTITLE:_PRINTIMAGE}} -The '''_PRINTIMAGE''' statement prints a colored image on the printer, stretching it to full paper size first. +The [[_PRINTIMAGE]] statement prints a colored image on the printer, stretching it to full paper size first. {{PageSyntax}} -::: '''_PRINTIMAGE''' ''imagehandle&'' +: [[_PRINTIMAGE]] {{Parameter|imageHandle&}} -* The imagehandle& is created by the [[_LOADIMAGE]], [[_NEWIMAGE]] or [[_COPYIMAGE]] functions. -* Use a WHITE background to save ink! [[CLS]] , 15 can be used to set the white background in any [[SCREEN]] mode. -* The image may be stretched disproportionately using normal screen sizes! To compensate, use a [[_NEWIMAGE]] screen that is proportional to the paper size. EX: A 640 X 900 SCREEN page is roughly the same as 3 times a 210mm X 297mm paper size. +* {{Parameter|imageHandle&}} is created by the [[_LOADIMAGE]], [[_NEWIMAGE]] or [[_COPYIMAGE]] functions. +* Use a white background to save ink. {{InlineCode}}[[CLS]] , _RGB(255, 255, 255){{InlineCodeEnd}} can be used to set the white background in any [[SCREEN]] mode. +* The image may be stretched disproportionately using normal screen sizes. To compensate, use a [[_NEWIMAGE]] screen that is proportional to the paper size. ''e.g.'' A 640 X 900 SCREEN page is roughly the same as 3 times a 210mm X 297mm paper size. * [[_NEWIMAGE]] or graphic screen pages can use [[_PRINTSTRING]] to print different sized text [[_FONT]]s. * [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] +{{PageExamples}} ''Example 1:'' Shows how to transfer custom font text on screen pages to the printer in Windows. Change the font path for other OS's. {{CodeStart}}PageScale = 10 PageHeight = 297 * PageScale 'A4 paper size is 210 X 297 mm @@ -65,7 +66,7 @@ CursorPosY = CursorPosY + FontHeight 'adjust print position down {{Cl|RETURN}} '' '' {{CodeEnd}} {{small|Code by Galleon}} -:''Explanation:'' CLS with the color white makes sure that the background is NOT printed a color! The PrintText [[GOSUB]] sets the [[COLOR]] of the text to red with a transparent background using [[_RGBA]] to set the [[_ALPHA]] transparency to zero or clear black. +:''Explanation:'' CLS with the color white makes sure that the background is not printed a color. The PrintText [[GOSUB]] sets the [[COLOR]] of the text to red with a transparent background using [[_RGBA]] to set the [[_ALPHA]] transparency to zero or clear black. ''Example 2:'' Printing an old SCREEN 12 [[ASCII]] table using a deeper sized page to prevent stretching by [[_PRINTIMAGE]]. @@ -159,7 +160,7 @@ Srow = 16 * (Trow - 1): Scol = 8 * (Tcol - 1) 'convert text to graphic coordinat :''Explanation:'' The [[ASCII]] character table was originally made in [[SCREEN]] 12 (640 X 480) and was adapted to 256 colors. -''See also:'' +{{PageSeeAlso}} * [[_LOADIMAGE]], [[_NEWIMAGE]] * [[_COPYIMAGE]] * [[LPRINT]] diff --git a/internal/help/_PRINTMODE.txt b/internal/help/_PRINTMODE.txt index 34508adb0..90de86452 100644 --- a/internal/help/_PRINTMODE.txt +++ b/internal/help/_PRINTMODE.txt @@ -1,26 +1,25 @@ {{DISPLAYTITLE:_PRINTMODE}} -The '''_PRINTMODE''' statement sets the text or [[_FONT]] printing mode on a background image when using [[PRINT]] or [[_PRINTSTRING]]. +The [[_PRINTMODE]] statement sets the text or [[_FONT]] printing mode on a background image when using [[PRINT]] or [[_PRINTSTRING]]. {{PageSyntax}} -:: '''_PRINTMODE''' {''_KEEPBACKGROUND''|''_ONLYBACKGROUND''|''_FILLBACKGROUND''}[, {{Parameter|image_handle}}] +: [[_PRINTMODE]] {''_KEEPBACKGROUND''|''_ONLYBACKGROUND''|''_FILLBACKGROUND''}[, {{Parameter|imageHandle&}}] {{Parameters}} -* One of 3 mode keywords is '''mandatory''' when using this statement to deal with the text background. - -:*''_KEEPBACKGROUND'' (mode 1): Text background transparent. Only the text is displayed over anything behind it. -:*''_ONLYBACKGROUND'' (mode 2): Text background is only displayed. Text is transparent to anything behind it. -:*''_FILLBACKGROUND'' (mode 3): Text and background block anything behind them like a normal [[PRINT]]. Default setting. -* If the optional image handle is omitted it will use the current [[_DEST|destination]] image background. -* If the optional image handle is 0 it will use the current program [[SCREEN]] image background. +* One of 3 mode keywords is mandatory when using this statement to deal with the text background. +**''_KEEPBACKGROUND'' (mode 1): Text background transparent. Only the text is displayed over anything behind it. +**''_ONLYBACKGROUND'' (mode 2): Text background only is displayed. Text is transparent to anything behind it. +**''_FILLBACKGROUND'' (mode 3): Text and background block anything behind them like a normal [[PRINT]]. '''Default setting.''' +* If the optional {{Parameter|imageHandle&}} is omitted or = 0) it will use the current [[_DEST|destination]] image background. {{PageDescription}} -* Use the [[_PRINTMODE (function)]] to find the current _PRINTMODE setting mode number. -* '''The _PRINTMODE statement and function can only be used in graphic screen modes, NOT SCREEN 0''' +* Use the [[_PRINTMODE (function)]] to find the current [[_PRINTMODE]] setting mode number. +* '''The _PRINTMODE statement and function can only be used in graphic screen modes, not SCREEN 0''' +{{PageExamples}} ''Example:'' Using _PRINTMODE with [[PRINT]] in a graphic screen mode. The background used is CHR$(219) = █ {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 12 diff --git a/internal/help/_PRINTMODE_(function).txt b/internal/help/_PRINTMODE_(function).txt index b49889650..e2857b097 100644 --- a/internal/help/_PRINTMODE_(function).txt +++ b/internal/help/_PRINTMODE_(function).txt @@ -1,22 +1,21 @@ {{DISPLAYTITLE:_PRINTMODE (function)}} -The '''_PRINTMODE''' function returns the present {{KW|_PRINTMODE}} status as a numerical value from 1 to 3 in graphic screen modes only. +The [[_PRINTMODE (function)|_PRINTMODE]] function returns the current [[_PRINTMODE]] status as a numerical value from 1 to 3 in graphic screen modes. {{PageSyntax}} -:::current_print_mode = '''_PRINTMODE'''[({{Parameter|image_handle}})] +: {{Parameter|currentPrintMode}} = [[_PRINTMODE (function)|_PRINTMODE]][({{Parameter|imageHandle&}})] {{Parameters}} -* If no brackets and ''image_handle'' parameter are given, the current [[_DEST|destination]] [[SCREEN]] page or image is assumed. -* If the handle value enclosed in brackets is 0 then the current program [[SCREEN]] page is assumed. +* If no {{Parameter|imageHandle&}} is given, the current [[_DEST|destination]] [[SCREEN]] page or image is assumed. {{PageDescription}} * Returns a status value from 1 to 3 designating the current mode setting: -::::'''1''': mode is _KEEPBACKGROUND -::::'''2''': mode is _ONLYBACKGROUND -::::'''3''': mode is _FILLBACKGROUND (default) -* '''The _PRINTMODE statement and function can only be used in graphic screen modes, NOT SCREEN 0''' +** '''1''': mode is _KEEPBACKGROUND +** '''2''': mode is _ONLYBACKGROUND +** '''3''': mode is _FILLBACKGROUND '''(default)''' +* '''The [[_PRINTMODE]] statement and function can only be used in graphic screen modes, not SCREEN 0''' {{PageSeeAlso}} diff --git a/internal/help/_PRINTSTRING.txt b/internal/help/_PRINTSTRING.txt index 2ebe16f95..0511172df 100644 --- a/internal/help/_PRINTSTRING.txt +++ b/internal/help/_PRINTSTRING.txt @@ -1,37 +1,34 @@ {{DISPLAYTITLE:_PRINTSTRING}} -The [[_PRINTSTRING]] statement prints text or custom font [[STRING|strings]] using graphic column and row coordinate positions. - +The [[_PRINTSTRING]] statement prints text [[STRING|strings]] using graphic column and row coordinate positions. {{PageSyntax}} -:: '''_PRINTSTRING ('''{{Parameter|column}}, {{Parameter|row}}'''),''' {{Parameter|text_expression$}}[, {{Parameter|image_handle&}}] +: [[_PRINTSTRING]]({{Parameter|column}}, {{Parameter|row}}), {{Parameter|textExpression$}}[, {{Parameter|imageHandle&}}] {{Parameters}} * {{Parameter|column}} and {{Parameter|row}} are [[INTEGER]] or [[LONG]] starting PIXEL (graphic) column and row coordinates to set text or custom fonts. -* {{Parameter|text_expression$}} is any literal or variable [[STRING|string]] value of text or fonts to be displayed. -* {{Parameter|image_handle&}} is the optional image or destination to use. Zero designates current [[SCREEN (statement)|SCREEN]] page. +* {{Parameter|textExpression$}} is any literal or variable [[STRING|string]] value of text to be displayed. +* {{Parameter|imageHandle&}} is the optional image or destination to use. Zero designates current [[SCREEN (statement)|SCREEN]] page. {{PageDescription}} * The starting coordinate sets the top left corner of the text to be printed. Use [[_FONTHEIGHT]] to calculate that text or [[_FONT|font]] position -* The [[_FONT]] size can affect the [[SCREEN (statement)|screen]] and row heights. Custom fonts are NOT required! Can print all [[ASCII]] characters. +* The [[_FONT]] size can affect the [[SCREEN (statement)|screen]] and row heights. +** Custom fonts are not required. [[_PRINTSTRING]] can print all [[ASCII]] characters. * [[_PRINTWIDTH]] can be used to determine how wide a text print will be so that the screen width is not exceeded. -* If the {{Parameter|image_handle&}} is omitted, the current image, page or screen destination is used. -* Can use the current font Alpha blending with a designated image background. See the [[_RGBA]] function example. -* Use the [[_PRINTMODE]] statement before a print to deal with the text background: -:*'''1''' _KEEPBACKGROUND: Text background transparent. Only the text is displayed over anything behind it. -:*'''2''' _ONLYBACKGROUND: Text background is only displayed. Text is transparent to anything behind it. -:*'''3''' _FILLBACKGROUND: Text and background block anything behind them like [[PRINT]]. Default setting. -* Use the [[_PRINTMODE (function)]] to find the current _PRINTMODE setting number. +* If the {{Parameter|imageHandle&}} is omitted, the current image, page or screen destination is used. +* Can use the current font alpha blending with a designated image background. See the [[_RGBA]] function example. +* Use the [[_PRINTMODE]] statement before printing to set how the background is rendered. +** Use the [[_PRINTMODE (function)]] to find the current _PRINTMODE setting. +* In SCREEN 0 (text only), [[_PRINTSTRING]] works as one-line replacement for '''LOCATE x, y: PRINT text$''', without changing the current cursor position. -{{PageErrors}} -* Coordinates MUST be located on the screen or image area or an [[ERROR Codes|"Illegal Function Call" error]] will occur. -* '''NOTE: _PRINTSTRING can only be used in graphic, 256 color or 32 bit screen modes, NOT SCREEN 0 in QB64-SDL versions.''' -* In QB64-GL versions, _PRINTSTRING works as '''LOCATE x, y: PRINT text$''' would while in SCREEN 0, without changing the current cursor position. +==Availability== +* In versions of QB64 prior to 1.000 _PRINTSTRING can only be used in graphic, 256 color or 32 bit screen modes, not SCREEN 0.'' +{{PageExamples}} ''Example 1:'' Printing those unprintable [[ASCII]] control characters is no longer a problem! {{CodeStart}} '' '' {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 256) @@ -47,11 +44,11 @@ The [[_PRINTSTRING]] statement prints text or custom font [[STRING|strings]] usi {{Cl|END}} '' '' {{CodeEnd}} {{OutputStart}} -  ☺ ☻ ♥ ♦ ♣ ♠ • ◘ ○ ◙ ♂ ♀ ♪ ♫ ☼ ► ◄ ↕ ‼ ¶ § ▬ ↨ ↑ ↓ → ← ∟ ↔ ▲ ▼ + ☺ ☻ ♥ ♦ ♣ ♠ • ◘ ○ ◙ ♂ ♀ ♪ ♫ ☼ ► ◄ ↕ ‼ ¶ § ▬ ↨ ↑ ↓ → ← ∟ ↔ ▲ ▼ {{OutputEnd}} -''Example 2:'' Making ANY '''QB64 program window''' larger using a SUB that easily converts PRINT to [[_PRINTSTRING]]. +''Example 2:'' Making any '''QB64 program window''' larger using a SUB that easily converts PRINT to [[_PRINTSTRING]]. {{CodeStart}} Scr13& = {{Cl|_NEWIMAGE}}(320, 200, 13) 'this is the old SCREEN 13 image page to set the image Big13& = {{Cl|_NEWIMAGE}}(640, 480, 256) 'use 4 X 3 aspect ratio that Qbasic used when full screen @@ -79,7 +76,7 @@ col% = ({{Cl|POS}}(0) - 1) * {{Cl|_PRINTWIDTH}}("W") 'finds current pa {{CodeEnd}} {{small|Code by Ted Weissgerber}} : ''Explanation:'' The procedure above creates a larger version of a SCREEN 13 window by stretching it with [[_PUTIMAGE]]. It cannot stretch PRINTed text so [[_PRINTSTRING]] must be used instead. [[LOCATE]] sets the PRINT cursor position for [[CSRLIN]] and [[POS]](0) to read. The SUB then converts the coordinates to graphical ones. Then '''change''' [[PRINT]] to PRINTS using the [[IDE]] '''Search Menu'''. -<center>[http://dl.dropbox.com/u/8440706/HOWIE.zip Download of Example 2 Bitmap images]</center> +<center>[https://www.dropbox.com/s/tcdik1ajegbeiz4/HOWIE.zip?dl=0 Download of Example 2 Bitmap images]</center> ''Example 3:'' Rotating a text string around a graphic object. @@ -113,9 +110,10 @@ row = 1 {{PageSeeAlso}} * [[_NEWIMAGE]], [[_PRINTWIDTH]], [[_PRINTMODE]] +* [[_CONTROLCHR]] {{text|(turns [[ASCII]] control characters OFF or ON)}} * [[_FONT]], [[_LOADFONT]], [[_FONTHEIGHT]], [[_FONTWIDTH]] * [[_SCREENIMAGE]], [[_SCREENPRINT]] -* [[Text Using Graphics]] {{text|(Demo)}} +* [[Text Using Graphics]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_PRINTWIDTH.txt b/internal/help/_PRINTWIDTH.txt index aceb566d9..1d523a6e5 100644 --- a/internal/help/_PRINTWIDTH.txt +++ b/internal/help/_PRINTWIDTH.txt @@ -1,21 +1,20 @@ {{DISPLAYTITLE:_PRINTWIDTH}}{{DISPLAYTITLE:}} -The [[_PRINTWIDTH]] function returns the width in pixels of the [[_FONT]] or text [[STRING|string]] that a program will print. - +The [[_PRINTWIDTH]] function returns the width in pixels of the text [[STRING|string]] specified. {{PageSyntax}} -::: pixel_width = '''_PRINTWIDTH('''{{Parameter|text_to_print$}}[, {{Parameter|destination_handle&}}]''')''' +: {{Parameter|pixelWidth%}} = [[_PRINTWIDTH]]({{Parameter|textToPrint$}}[, {{Parameter|destinationHandle&}}]) {{PageDescription}} -* {{Parameter|text_to_print$}} is any literal or variable [[STRING]] value. -* If the {{Parameter|destination_handle&}} is omitted, the current destination image or screen page is used. +* {{Parameter|textToPrint$}} is any literal or variable [[STRING]] value. +* If the {{Parameter|destinationHandle&}} is omitted, the current destination image or screen page is used. * Useful to find the width of the font print [[STRING|string]] before actually printing it. -* Can be used with '''variable''' width fonts or '''no font''' at all unlike [[_FONTWIDTH]] which requires MONOSPACE fonts only. -* '''_PRINTWIDTH cannot be used in SCREEN 0 in QB64-SDL version.''' -* '''QB64-GL''' does support SCREEN 0 use of _PRINTWIDTH which will return the character length of text exactly as [[LEN]](text$) would. +* Can be used with variable-width fonts or built-in fonts, unlike [[_FONTWIDTH]] which requires a MONOSPACE font handle. +* In SCREEN 0, _PRINTWIDTH returns the character length of a text string, exactly as [[LEN]]({{Parameter|textToPrint$}}) ('''version 1.000 and up'''). +{{PageExamples}} ''Example:'' SUB returns font or screen mode's text block size using _PRINTWIDTH and [[_FONTHEIGHT]] without a handle parameter. {{CodeStart}} '' '' {{Cl|DO}} @@ -47,7 +46,7 @@ TextHeight& = {{Cl|_FONTHEIGHT}} 'can measure normal text block heig * [[_FONTWIDTH]], [[_FONTHEIGHT]] * [[_NEWIMAGE]], [[_LOADFONT]] * [[_PRINTSTRING]], [[_FONT]] -* [[Text Using Graphics]] (Demo) +* [[Text Using Graphics]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_PUTIMAGE.txt b/internal/help/_PUTIMAGE.txt index 82ab3a351..ba94bd83b 100644 --- a/internal/help/_PUTIMAGE.txt +++ b/internal/help/_PUTIMAGE.txt @@ -1,64 +1,64 @@ {{DISPLAYTITLE:_PUTIMAGE}} -The [[_PUTIMAGE]] statement puts an area of a source image to an area of a destination image in one operation like [[GET (graphics statement)|GET]] and [[PUT (graphics statement)|PUT]]. +[[_PUTIMAGE]] puts an area of a source image to an area of a destination image in one operation, like [[GET (graphics statement)|GET]] and [[PUT (graphics statement)|PUT]]. {{PageSyntax}} +:[[_PUTIMAGE]] [STEP] [({{Parameter|dx1}}, {{Parameter|dy1}})-[STEP][({{Parameter|dx2}}, {{Parameter|dy2}})]][, {{Parameter|sourceHandle&}}][, {{Parameter|destHandle&}}][, ][STEP][({{Parameter|sx1}}, {{Parameter|sy1}})[-STEP][({{Parameter|sx2}}, {{Parameter|sy2}})]][''_SMOOTH''] -'''_PUTIMAGE''' [STEP] [(''dx1'', ''dy1'')-[STEP][(''dx2'', ''dy2'')]][, ''source_handle''][, ''dest_handle''][, ][STEP][(''sx1'', ''sy1'')[-STEP][(''sx2'', ''sy2'')]][_SMOOTH] +===Sample usage=== -:::or… +::[[_PUTIMAGE]] {{text|'full source image to fit full destination area after [[_SOURCE]] and [[_DEST]] are set}} -::_PUTIMAGE {{text|'full source image to fit full destination area after [[_SOURCE]] and [[_DEST]] are set}} +::[[_PUTIMAGE]] , {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}} {{text|'size full source to fit full destination area}} -::_PUTIMAGE , ''source_handle'', ''dest_handle'' {{text|'size full source to fit full destination area}} +::[[_PUTIMAGE]] (''dx1'', ''dy1''), {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}} {{text|'full source to top-left corner destination position}} -::_PUTIMAGE (''dx1'', ''dy1''), ''source_handle'', ''dest_handle'' {{text|'full source to TL corner destination position}} +::[[_PUTIMAGE]] (''dx1'', ''dy1'')-(''dx2'', ''dy2''), {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}} {{text|'size full source to destination coordinate area}} -::_PUTIMAGE (''dx1'', ''dy1'')-(''dx2'', ''dy2''), ''source_handle'', ''dest_handle'' {{text|'size full source to destination coordinate area}} +::[[_PUTIMAGE]] (''dx1'', ''dy1''), {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}}, (''sx1'', ''sy1'')-(''sx2'', ''sy2'') {{text|'portion of source to the top-left corner of the destination page}} -::_PUTIMAGE (''dx1'', ''dy1''), ''source_handle'',''dest_handle'', (''sx1'', ''sy1'')-(''sx2'', ''sy2'') {{text|'portion of source to TL corner of destination}} +::[[_PUTIMAGE]] , {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}}, (''sx1'', ''sy1'')-(''sx2'', ''sy2'') {{text|'portion of source to full destination area}} -::_PUTIMAGE , ''source_handle'', ''dest_handle'', (''sx1'', ''sy1'')-(''sx2'', ''sy2'') {{text|'portion of source to full destination area}} - -::_PUTIMAGE (''dx1'', ''dy1'')-(''dx2'', ''dy2''), ''source_handle'', ''dest_handle'',(''sx1'', ''sy1'') {{text|'right side of source from TL corner to destination}} +::[[_PUTIMAGE]] (''dx1'', ''dy1'')-(''dx2'', ''dy2''), {{Parameter|sourceHandle&}}, {{Parameter|destHandle&}},(''sx1'', ''sy1'') {{text|'right side of source from top-left corner to destination}} -::Note: The Top Left corner position designates the leftmost and top-most portion of the image to use. +::Note: The top-left corner position designates the leftmost and topmost portion of the image to use. {{Parameters}} -* Relative coordinates to a previous '''GL''' graphical object can be designated using [[STEP]] as opposed to literal surface coordinates. +* Relative coordinates to a previous graphical object can be designated using [[STEP]] as opposed to literal surface coordinates (version '''1.000''' and up). * Coordinates ''dx'' and ''dy'' map the box area of the [[_DEST|destination]] area to use. When omitted the entire desination area is used. If only one coordinate is used, the source is placed with its original dimensions. Coordinates can be set to flip or resize the image. -:* {{Parameter|dx1}} = the column coordinate at which the insertion of the source will begin(left-most): When larger than ''dx2'' reverses image. -:* {{Parameter|dy1}} = the row coordinate at which the insertion of the source will begin(top-most): When larger than ''dy2'' inverts image. -:* {{Parameter|dx2}} = the column coordinate at which the insertion of the source will end(right-most): Further apart widens image. -:* {{Parameter|dy2}} = the row coordinate at which the insertion of the source will end(bottom-most): Closer together shrinks image -* {{Parameter|source_handle}} = the [[LONG]] handle of the [[_SOURCE|source]] image created with [[_NEWIMAGE]], [[_LOADIMAGE]] or [[_COPYIMAGE]]. -* {{Parameter|dest_handle}} = the [[LONG]] handle of the [[_DEST|destination]] image may be created with [[_NEWIMAGE]], [[SCREEN]] or [[_DEST|destination]] 0. +** {{Parameter|dx1}} = the column coordinate at which the insertion of the source will begin (leftmost); when larger than ''dx2'', reverses image. +** {{Parameter|dy1}} = the row coordinate at which the insertion of the source will begin (topmost); when larger than ''dy2'', inverts image. +** {{Parameter|dx2}} = the column coordinate at which the insertion of the source will end (rightmost); further apart, widens image. +** {{Parameter|dy2}} = the row coordinate at which the insertion of the source will end (bottommost); closer together, shrinks image +* {{Parameter|sourceHandle&}} = the [[LONG]] handle of the [[_SOURCE|source]] image created with [[_NEWIMAGE]], [[_LOADIMAGE]] or [[_COPYIMAGE]]. +* {{Parameter|destHandle&}} = the [[LONG]] handle of the [[_DEST|destination]] image may be created with [[_NEWIMAGE]], [[SCREEN]] or [[_DEST|destination]] 0. * Coordinates ''sx'' and ''sy'' [[GET (graphics statement)|GET]] the box area of the [[_SOURCE|source]] image to transfer to the [[_DEST|destination]] image, page or [[SCREEN|screen]]: -:* {{Parameter|sx1}} = the column coordinate of the left-most pixel to include of the source. When omitted the entire image is used -:* {{Parameter|sy1}} = the row coordinate of the upper-most pixel to include of the source. When omitted the entire image is used -:* {{Parameter|sx2}} = the column coordinate of the right-most pixel to include of the source. Can be omitted to get rest of image. -:* {{Parameter|sy2}} = the row coordinate of the bottom-most pixel to include of the source. Can be omitted to get rest of image. -* Supports an optional final argument called '''_SMOOTH''' which applies linear filtering in '''QB64GL'''. +** {{Parameter|sx1}} = the column coordinate of the left-most pixel to include of the source. When omitted, the entire image is used +** {{Parameter|sy1}} = the row coordinate of the upper-most pixel to include of the source. When omitted, the entire image is used +** {{Parameter|sx2}} = the column coordinate of the right-most pixel to include of the source. Can be omitted to get rest of image. +** {{Parameter|sy2}} = the row coordinate of the bottom-most pixel to include of the source. Can be omitted to get rest of image. +* ''_SMOOTH'' applies linear filtering ('''version 1.000 and up'''). -<center>'''Note: The [[PUT (graphics statement)|PUT]] options PSET, PRESET, AND, OR and XOR are not available with _PUTIMAGE. QB64 can use [[_ALPHA|transparency]] of colors to do those things.'''</center> +<center>'''Note: The [[PUT (graphics statement)|PUT]] options PSET, PRESET, AND, OR and XOR are not available with _PUTIMAGE. QB64 can use [[_ALPHA|transparency]] of colors to achieve the same results.'''</center> -''Usage:'' +{{PageDescription}} * _PUTIMAGE can be used without any handle parameters if the [[_SOURCE]] and/or [[_DEST]] are already defined. -* '''The {{Parameter|source_handle}} and {{Parameter|dest_handle}} cannot be the same! If they are it will return an [[ERROR Codes|Illegal Function Call]] error.''' +* '''The {{Parameter|sourceHandle&}} and {{Parameter|destHandle&}} cannot be the same or an [[ERROR Codes|Illegal Function Call]] error will occur.''' * If the area of the source is bigger or smaller than the area of the destination then the image is adjusted to fit that area. -* Supports 32 bit alpha blending, color key transparency, true type fonts, stretching, mirroring/flipping, and a variety of graphics file formats including gif, png, bmp & jpg. '''32 bit screen surface backgrounds(black) have zero [[_ALPHA]] and are transparent when placed over other surfaces.''' Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opague. +* Supports 32 bit alpha blending, color key transparency, true type fonts, stretching, mirroring/flipping, and a variety of graphics file formats including gif, png, bmp & jpg. '''32 bit screen surface backgrounds (black) have zero [[_ALPHA]] and are transparent when placed over other surfaces.''' Use [[CLS]] or [[_DONTBLEND]] to make a new surface background [[_ALPHA]] 255 or opaque. * All graphical surfaces, including screen pages, can be acted upon in the same manner, and are referred to as "images". * '''Hardware images''' (created using mode '''33''' via [[_LOADIMAGE]] or [[_COPYIMAGE]]) can be used as the source or destination. -* Handles are used to identify graphical surfaces. Positive values are used to refer to screen pages. -1 (negative one) indicates an invalid surface. It is recommended that image handles be stored in LONG variables. Passing an invalid handle generates an [[ERROR Codes|"Invalid handle"]] error. Font handles also use -1 to indicate an invalid font. +* [[Handle]]s are used to identify graphical surfaces. Positive values are used to refer to screen pages. -1 (negative one) indicates an invalid surface. It is recommended to store image handles in [[LONG]] variables. Passing an invalid handle generates an [[ERROR Codes|"Invalid handle"]] error. * When handles are not passed (or cannot be passed) to subs/functions then the default destination image or source image is referenced. These are set to the active page when the SCREEN statement is called, but can be changed to any image. So it is possible to read from one image using [[POINT]] and write to a different one with [[PSET]]. -* '''[[PRINT]]ed text cannot be transferred and positioned accurately!''' Use [[_PRINTSTRING]] for graphical text or font placement. +* '''[[PRINT]]ed text cannot be transferred and positioned accurately.''' Use [[_PRINTSTRING]] for graphical text or font placement. * '''Images are not deallocated when the [[SUB]] or [[FUNCTION]] they are created in ends. Free them with [[_FREEIMAGE]].''' -* '''It is IMPORTANT to free discarded or unused images with [[_FREEIMAGE]] to prevent CPU memory overflow errors!''' +* '''It is important to free discarded or unused images with [[_FREEIMAGE]] to prevent CPU memory overflow errors.''' +{{PageExamples}} ''Example 1:'' {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} 13 @@ -73,9 +73,9 @@ The [[_PUTIMAGE]] statement puts an area of a source image to an area of a desti : 2) A new image is created that is 640 X 200 and uses the palette compatible with SCREEN 13 (256 colors). : 3) [[_DEST]] a& makes the image with handle 'a&' the default image to draw on instead of the screen (which is [[_DEST]] 0). : 4) Next a filled box (BF) is drawn from 10, 10 to 100, 100 with red color (12) to the destination image (set by [[_DEST]] a&) -: 5) Now we put the image from 0, 0 to 320, 200 from the image with the handle 'a&' to the screen (always handle 0) and puts this image into the coordinates 0, 0 to 320, 200. If we want to stretch the image we can alter these coordinates (do try this!) +: 5) Now we put the image from 0, 0 to 320, 200 from the image with the handle 'a&' to the screen (always handle 0) and puts this image into the coordinates 0, 0 to 320, 200. If we want to stretch the image we can alter these coordinates. -:'''Note:''' All arguments are optional. If you want to simply put the whole image of the source to the whole image of the destination then you omit the area (x, y)-(x2, y2) on both sides, the last line of the example can be replaced by {{KW|_PUTIMAGE}} , a&, 0 which indeed will stretch the image since image a& is bigger than the screen (the screen is 320 * 200 and a& is 640 * 200) +:'''Note:''' All arguments are optional. If you want to simply put the whole image of the source to the whole image of the destination then you omit the area (x, y)-(x2, y2) on both sides, the last line of the example can be replaced by [[_PUTIMAGE]] , a&, 0 which indeed will stretch the image since image a& is bigger than the screen (the screen is 320 * 200 and a& is 640 * 200) ''Example 2: ''You don't need to do anything special to use a .PNG image with alpha/transparency. Here's a simple example: @@ -179,11 +179,9 @@ h& = {{Cl|_NEWIMAGE}}(640, 480, 256) -''See Examples:'' - -[[Bitmaps]] (Bitmap Screenshots) - -[[SAVEIMAGE]] (Converts Images to Bitmaps) +===More examples=== +* [[Bitmaps]] (Bitmap Screenshots) +* [[SAVEIMAGE]] (Converts Images to Bitmaps) {{PageSeeAlso}} diff --git a/internal/help/_R2D.txt b/internal/help/_R2D.txt index 0b068896b..25a666d52 100644 --- a/internal/help/_R2D.txt +++ b/internal/help/_R2D.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_R2D}} -The '''_R2D''' function converts a RADIAN value into a DEGREE value. +The [[_R2D]] function converts a '''radian''' value into a '''degree''' value. {{PageSyntax}} -:: result = [[_R2D]](''num'') +: {{Parameter|result!}} = [[_R2D]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Radian into Degree. {{CodeStart}} INPUT "Give me an angle in Radians ", D @@ -21,7 +23,7 @@ That angle in Degrees is 28.64789 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]], [[_D2R]] * [[_G2D]], [[_G2R]] * [[_R2G]] diff --git a/internal/help/_R2G.txt b/internal/help/_R2G.txt index 4b25eeafd..234a23831 100644 --- a/internal/help/_R2G.txt +++ b/internal/help/_R2G.txt @@ -1,14 +1,16 @@ {{DISPLAYTITLE:_R2G}} -The '''_R2G''' function converts a RADIAN value into a GRADIENT value. +The [[_R2G]] function converts a '''radian''' value into a '''gradient''' value. {{PageSyntax}} -:: result = [[_R2G]](''num'') +: {{Parameter|result!}} = [[_R2G]]({{Parameter|num}}) -*(Only available in QB64-GL, from Dirty Builds after 06/20/2014. Previous versions of QB64 don't support this command.) +==Availability== +* '''Version 1.000 and up.''' +{{PageExamples}} ''Example:'' Coverting Radian into Gradient. {{CodeStart}} INPUT "Give me an angle in Radians ", D @@ -21,7 +23,7 @@ That angle in Gradient is 31.83099 {{OutputEnd}} -''See also:'' +{{PageSeeAlso}} * [[_D2G]], [[_D2R]] * [[_G2D]], [[_G2R]] * [[_R2D]] diff --git a/internal/help/_RED.txt b/internal/help/_RED.txt index 3ea014604..4922e9fc2 100644 --- a/internal/help/_RED.txt +++ b/internal/help/_RED.txt @@ -3,23 +3,23 @@ The [[_RED]] function returns the palette index or the red component intensity o {{PageSyntax}} -:: redintensity& = '''_RED('''{{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]''')''' +: {{Parameter|redIntensity&}} = [[_RED]]({{Parameter|rgbaColorIndex&}}[, {{Parameter|imageHandle&}}]) {{PageDescription}} * {{Parameter|rgbaColorIndex&}} is the ''RGBA'' color value or palette index of the color to retrieve the red component intensity from. * The [[LONG]] intensity value returned ranges from 0 (no intensity, not present) to 255 (full intensity). +* {{Parameter|imageHandle&}} is optional. * If {{Parameter|imageHandle&}} specifies a 32-bit color image, {{Parameter|rgbaColorIndex&}} is interpreted as a 32-bit ''RGBA'' color value. * If {{Parameter|imageHandle&}} specifies an image that uses a palette, {{Parameter|rgbaColorIndex&}} is interpreted as a palette index. * If {{Parameter|imageHandle&}} is not specified, it is assumed to be the current write page. * If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|invalid handle]] error occurs. * If {{Parameter|rgbaColorIndex&}} is outside the range of valid indexes for a given image mode, an [[ERROR Codes|illegal function call]] error occurs. -* Uses index parameters passed by the {{KW|_RGB}}, {{KW|_RGBA}}, {{KW|_RGB32}} or {{KW|_RGBA32}} funtions. -* An image handle is optional. +* Uses index parameters passed by the [[_RGB]], [[_RGBA]], [[_RGB32]] or [[_RGBA32]] functions. -''See Example:'' -* [[POINT]] +{{PageExamples]] +* See the example in [[POINT]]. {{PageSeeAlso}} diff --git a/internal/help/_RED32.txt b/internal/help/_RED32.txt index c4cc3a6ad..809c306f3 100644 --- a/internal/help/_RED32.txt +++ b/internal/help/_RED32.txt @@ -1,19 +1,19 @@ {{DISPLAYTITLE:_RED32}} -The [[_RED32]] function always returns the red component intensity of a 32-bit image or surface color. +The [[_RED32]] function returns the red component intensity of a 32-bit image or surface color. {{PageSyntax}} -:: red32color& = '''_RED32('''{{Parameter|rgbaColor&}}''')''' +: {{Parameter|red32color&}} = [[_RED32]]({{Parameter|rgbaColor&}}) {{PageDescription}} * {{Parameter|rgbaColor&}} is the 32-bit ''RGBA'' color value to retrieve the red component intensity value from. -* ''RGBA'' color values are returned by the {{KW|_PALETTECOLOR (function)|_PALETTECOLOR}}, {{KW|POINT}}, {{KW|_RGB}}, {{KW|_RGB32}}, {{KW|_RGBA}} or {{KW|_RGBA32}} functions. +* ''RGBA'' color values are returned by the [[_PALETTECOLOR (function)|_PALETTECOLOR]], [[POINT]], [[_RGB]], [[_RGB32]], [[_RGBA]] or [[_RGBA32]] functions. * [[LONG]] intensity values returned range from 0 (no intensity, not present) to 255 (full intensity). -''See Example:'' -* [[POINT]] +{{PageExamples}} +* See the example in [[POINT]]. {{PageSeeAlso}} diff --git a/internal/help/_RESIZE.txt b/internal/help/_RESIZE.txt index 9b63b4355..0224e9d35 100644 --- a/internal/help/_RESIZE.txt +++ b/internal/help/_RESIZE.txt @@ -1,9 +1,9 @@ {{DISPLAYTITLE:_RESIZE}} -The '''_RESIZE''' statement sets resizing of the window ON or OFF and sets the method as _STRETCH or _SMOOTH. +The [[_RESIZE]] statement sets resizing of the window ON or OFF and sets the method as _STRETCH or _SMOOTH. {{PageSyntax}} -::: '''_RESIZE''' [{ON|OFF}][, {_STRETCH|_SMOOTH}] +: [[_RESIZE]] [{ON|OFF}][, {_STRETCH|_SMOOTH}] {{Parameters}} @@ -12,9 +12,7 @@ The '''_RESIZE''' statement sets resizing of the window ON or OFF and sets the m {{PageDescription}} - - -{{PageErrors}} +* Before this statement can be used, you must add the [[$RESIZE]]''':ON''' metacommand to your program. {{PageSeeAlso}} diff --git a/internal/help/_RESIZEHEIGHT.txt b/internal/help/_RESIZEHEIGHT.txt index 3b1cf8740..d16214cb1 100644 --- a/internal/help/_RESIZEHEIGHT.txt +++ b/internal/help/_RESIZEHEIGHT.txt @@ -1,20 +1,53 @@ {{DISPLAYTITLE:_RESIZEHEIGHT}} -The [[_RESIZEHEIGHT]] function returns the user re-sized screen pixel width if [[$RESIZE]]:ON allows it and [[_RESIZE (function)|_RESIZE]] returns -1 +The [[_RESIZEHEIGHT]] function returns the user resized screen pixel height if [[$RESIZE]]:ON allows it and [[_RESIZE (function)|_RESIZE]] returns -1 {{PageSyntax}} -::: newHeight& = '''_RESIZEHEIGHT''' +: {{Parameter|newHeight&}} = [[_RESIZEHEIGHT]] -''Details:'' -* [[_RESIZE (function)|_RESIZE]] function must return -1 before the requested screen dimensions can be returned by the function. -* The program should decide if the request is allowable for proper program interactions and view-ability. -* '''QB64 GL''' programs only. Not available in QB64 SDL versions .954 and older. +{{Parameter|Details:}} +* [[_RESIZE (function)|_RESIZE]] function must return true (-1) before the requested screen dimensions can be returned by the function. +* The program should decide if the request is allowable for proper program interaction. -''See also:'' -* [[$RESIZE]] {{text|(ON allows user to resize)}} -* [[_RESIZE (function)]] {{text|(returns user resize request)}} +==Availability== +* '''Version 1.000 and up'''. + + +{{PageExamples}} +''Example:'' Resize the current screen image according to user's request. +{{CodeStart}} +{{Cl|$RESIZE}}:ON + +s& = {{Cl|_NEWIMAGE}}(300, 300, 32) +{{Cl|SCREEN}} s& + +bee& = {{Cl|_LOADIMAGE}}("qb64_trans.png") 'QB64's bee from http://www.qb64.net/qb64_trans.png + +{{Cl|DO}} + {{Cl|IF}} {{Cl|_RESIZE (function)|_RESIZE}} THEN + oldimage& = s& + s& = _NEWIMAGE(_RESIZEWIDTH, _RESIZEHEIGHT, 32) + SCREEN s& + {{Cl|_FREEIMAGE}} oldimage& + END IF + + {{Cl|CLS}} + + 'Center the QB64 bee image: + x = {{Cl|_WIDTH (function)|_WIDTH}} / 2 - _WIDTH(bee&) / 2 + y = {{Cl|_HEIGHT}} / 2 - _HEIGHT(bee&) / 2 + {{Cl|_PUTIMAGE}} (x, y), bee& + {{Cl|_DISPLAY}} + {{Cl|_LIMIT}} 30 +{{Cl|LOOP}} +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[$RESIZE]] +* [[_RESIZE (function)]] * [[_RESIZEWIDTH]] diff --git a/internal/help/_RESIZEWIDTH.txt b/internal/help/_RESIZEWIDTH.txt index daf4af82b..6ba39663f 100644 --- a/internal/help/_RESIZEWIDTH.txt +++ b/internal/help/_RESIZEWIDTH.txt @@ -1,20 +1,53 @@ {{DISPLAYTITLE:_RESIZEWIDTH}} -The [[_RESIZEWIDTH]] finction returns the user re-sized screen pixel width if [[$RESIZE]]:ON allows it and [[_RESIZE (function)|_RESIZE]] returns -1 +The [[_RESIZEWIDTH]] function returns the user resized screen pixel width if [[$RESIZE]]:ON allows it and [[_RESIZE (function)|_RESIZE]] returns -1 {{PageSyntax}} -::: newWidth& = '''_RESIZEWIDTH''' +: {{Parameter|newWidth&}} = [[_RESIZEWIDTH]] -''Details:'' -* [[_RESIZE (function)|_RESIZE]] function must return -1 before the requested screen dimensions can be returned by the function. -* The program should decide if the request is allowable for proper program interactions and view-ability. -* '''QB64 GL''' programs only. Not available in QB64 SDL versions .954 and older. +{{PageDescription}} +* [[_RESIZE (function)|_RESIZE]] function must return true (-1) before the requested screen dimensions can be returned by the function. +* The program should decide if the request is allowable for proper program interaction. -''See also:'' -* [[$RESIZE]] {{text|(ON allows user to resize)}} -* [[_RESIZE (function)]] {{text|(returns user resize request)}} +==Availability== +* '''Version 1.000 and up'''. + + +{{PageExamples}} +''Example:'' Resize the current screen image according to user's request. +{{CodeStart}} +{{Cl|$RESIZE}}:ON + +s& = {{Cl|_NEWIMAGE}}(300, 300, 32) +{{Cl|SCREEN}} s& + +bee& = {{Cl|_LOADIMAGE}}("qb64_trans.png") 'QB64's bee from http://www.qb64.net/qb64_trans.png + +{{Cl|DO}} + {{Cl|IF}} {{Cl|_RESIZE (function)|_RESIZE}} THEN + oldimage& = s& + s& = _NEWIMAGE(_RESIZEWIDTH, _RESIZEHEIGHT, 32) + SCREEN s& + {{Cl|_FREEIMAGE}} oldimage& + END IF + + {{Cl|CLS}} + + 'Center the QB64 bee image: + x = {{Cl|_WIDTH (function)|_WIDTH}} / 2 - _WIDTH(bee&) / 2 + y = {{Cl|_HEIGHT}} / 2 - _HEIGHT(bee&) / 2 + {{Cl|_PUTIMAGE}} (x, y), bee& + {{Cl|_DISPLAY}} + {{Cl|_LIMIT}} 30 +{{Cl|LOOP}} +{{CodeEnd}} + + +{{PageSeeAlso}} +* [[$RESIZE]] +* [[_RESIZE (function)]] * [[_RESIZEHEIGHT]] diff --git a/internal/help/_RESIZE_(function).txt b/internal/help/_RESIZE_(function).txt index d726b8df3..89d509d7c 100644 --- a/internal/help/_RESIZE_(function).txt +++ b/internal/help/_RESIZE_(function).txt @@ -1,19 +1,52 @@ {{DISPLAYTITLE:_RESIZE (function)}} -The '''_RESIZE''' function returns -1 when a user has attempted to resize the program window and [[$RESIZE]]:ON has allowed it. +The [[_RESIZE]] function returns true (-1) when a user has attempted to resize the program window and [[$RESIZE]]:ON has allowed it. {{PageSyntax}} -::: IF '''_RESIZE''' THEN rx& = [[_RESIZEWIDTH]]: ry& = [[_RESIZEHEIGHT]] +: IF '''_RESIZE''' THEN rx& = [[_RESIZEWIDTH]]: ry& = [[_RESIZEHEIGHT]] -''Details:'' -* The function returns -1 if a program screen re-size was attempted by the user. -* After the function returns -1, [[_RESIZEWIDTH]] and [[_RESIZEHEIGHT]] can return the new dimensions in pixels. +{{PageDescription}} +* The function returns -1 if a program screen resize was attempted by the user. +* After the function returns -1, [[_RESIZEWIDTH]] and [[_RESIZEHEIGHT]] can return the new requested dimensions in pixels. * The [[$RESIZE]]:ON [[metacommand]] must be used so the program is created with a user resizable window. -* '''QB64 GL''' programs only. Not available in QB64 SDL versions .954 and older. -''See also:'' +==Availability== +* '''Version 1.000 and up'''. + + +{{PageExamples}} +''Example:'' Resize the current screen image according to user's request. +{{CodeStart}} +{{Cl|$RESIZE}}:ON + +s& = {{Cl|_NEWIMAGE}}(300, 300, 32) +{{Cl|SCREEN}} s& + +bee& = {{Cl|_LOADIMAGE}}("qb64_trans.png") 'QB64's bee from http://www.qb64.net/qb64_trans.png + +{{Cl|DO}} + {{Cl|IF}} {{Cl|_RESIZE (function)|_RESIZE}} THEN + oldimage& = s& + s& = _NEWIMAGE(_RESIZEWIDTH, _RESIZEHEIGHT, 32) + SCREEN s& + {{Cl|_FREEIMAGE}} oldimage& + END IF + + {{Cl|CLS}} + + 'Center the QB64 bee image: + x = {{Cl|_WIDTH (function)|_WIDTH}} / 2 - _WIDTH(bee&) / 2 + y = {{Cl|_HEIGHT}} / 2 - _HEIGHT(bee&) / 2 + {{Cl|_PUTIMAGE}} (x, y), bee& + {{Cl|_DISPLAY}} + {{Cl|_LIMIT}} 30 +{{Cl|LOOP}} +{{CodeEnd}} + + +{{PageSeeAlso}} * [[$RESIZE]] {{text|(metacommand)}} * [[_RESIZE]] * [[_RESIZEWIDTH]], [[_RESIZEHEIGHT]] {{text|(requested pixel dimensions)}} diff --git a/internal/help/_RGB.txt b/internal/help/_RGB.txt index 276d7a423..761177c0a 100644 --- a/internal/help/_RGB.txt +++ b/internal/help/_RGB.txt @@ -1,23 +1,26 @@ {{DISPLAYTITLE:_RGB}} -The [[_RGB]] function returns the closest palette attribute index OR the [[LONG]] 32 bit color value in 32 bit screens only. +The [[_RGB]] function returns the closest palette attribute index (legacy SCREEN modes) OR the [[LONG]] 32-bit color value (32-bit screens). -:colorindex~& = '''_RGB('''{{Parameter|red}}, {{Parameter|green}}, {{Parameter|blue}}[, {{Parameter|image_handle}}]''')''' +{{PageSyntax}} +: {{Parameter|colorIndex~&}} = [[_RGB]]({{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}[, {{Parameter|imageHandle&}}]) -* The value returned is either the closest color attribute number or a 32 bit [[_UNSIGNED]] [[LONG]] color value. -* '''Return variable types MUST be [[LONG]] or resulting color may lose the [[_BLUE]] value!''' +{{PageDescription}} +* The value returned is either the closest color attribute number or a 32-bit [[_UNSIGNED]] [[LONG]] color value. +* '''Return variable types must be [[LONG]] or resulting color may lose the [[_BLUE]] value.''' * {{Parameter|red&}} specifies the red component intensity from 0 to 255. * {{Parameter|green&}} specifies the green component intensity from 0 to 255. * {{Parameter|blue&}} specifies the blue component intensity from 0 to 255. * Intensity values outside the valid range are clipped. -* Returns [[LONG]] 32 bit hexadecimal values from '''&HFF{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with full [[_ALPHA]] only. -* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]](colorvalue&), 3) to place 3 colors. -* If the ''image_handle'' is omitted the image is assumed to be the current [[_DEST|destination]] or [[SCREEN]] page. -* Colors returned are ALWAYS opaque as the transparency value is always 255! Use [[_ALPHA]] or [[_CLEARCOLOR]] to change it. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* Returns [[LONG]] 32-bit hexadecimal values from '''&HFF{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''', always with full [[_ALPHA]]. +* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]]({{Parameter|colorIndex~&}}), 3) to place 3 colors. +* If the {{Parameter|imageHandle&}} is omitted the image is assumed to be the current [[_DEST|destination]] or [[SCREEN]] page. +* Colors returned are always opaque as the transparency value is always 255. Use [[_ALPHA]] or [[_CLEARCOLOR]] to change it. +* '''NOTE: Default 32-bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' +{{PageExamples}} ''Example:'' Converting the color port RGB intensity palette values 0 to 63 to 32 bit hexadecimal values. {{CodeStart}} {{Cl|SCREEN}} 12 @@ -56,7 +59,7 @@ The [[_RGB]] function returns the closest palette attribute index OR the [[LONG] * [[_RED]], [[_GREEN]], [[_BLUE]] * [[_LOADIMAGE]], [[_NEWIMAGE]] * [[HEX$ 32 Bit Values]], [[POINT]] -* [[SAVEIMAGE]] {{text|(bitmap creator)}} +* [[SAVEIMAGE]] * [http://www.w3schools.com/html/html_colornames.asp Hexadecimal Color Values] diff --git a/internal/help/_RGB32.txt b/internal/help/_RGB32.txt index 5be4f1738..6aa0fde0d 100644 --- a/internal/help/_RGB32.txt +++ b/internal/help/_RGB32.txt @@ -1,27 +1,28 @@ {{DISPLAYTITLE:_RGB32}} -The [[_RGB32]] function ALWAYS returns the 32-bit ''RGBA'' color value with specified red, green and blue component intensities. +The [[_RGB32]] function returns the 32-bit ''RGBA'' color value with specified red, green and blue component intensities. {{PageSyntax}} -:{{Parameter|color32value~&}} = '''_RGB32('''{{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}''')''' +:{{Parameter|color32value~&}} = [[_RGB32]]({{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}) -{{Parameters} +{{Parameters}} * {{Parameter|red&}} specifies the red [[LONG]] component intensity from 0 to 255. * {{Parameter|green&}} specifies the green [[LONG]] component intensity from 0 to 255. * {{Parameter|blue&}} specifies the blue [[LONG]] component intensity from 0 to 255. {{PageDescription}} -* The value returned is ALWAYS a 32 bit [[_UNSIGNED]] [[LONG]] color value as is the [[POINT]] value. -* '''Return variable types MUST be [[LONG]] or resulting color may lose the [[_BLUE]] value!''' +* The value returned is ALWAYS a 32-bit [[_UNSIGNED]] [[LONG]] color value, as is the [[POINT]] value. +* '''Return variable types must be [[LONG]] or resulting color may lose the [[_BLUE]] value.''' * Color intensity values outside of the 0 to 255 range are clipped. -* Returns [[LONG]] 32 bit hexadecimal values from '''&HFF{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with full [[_ALPHA]] only. -* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]](colorvalue&), 3) to place 3 colors. -* Colors returned are ALWAYS opaque as the transparency value is always 255! Use [[_ALPHA]] or [[_CLEARCOLOR]] to change it. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* Returns [[LONG]] 32 bit hexadecimal values from '''&HFF{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''', always with full [[_ALPHA]]. +* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]]({{Parameter|color32value~&}}), 3) to place 3 colors. +* Colors returned are always opaque as the transparency value is always 255. Use [[_ALPHA]] or [[_CLEARCOLOR]] to change it. +* '''NOTE: Default 32-bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' +{{PageExamples}} ''Example 1:'' Converting the color port RGB intensity palette values 0 to 63 to 32 bit hexadecimal values. {{CodeStart}} {{Cl|SCREEN}} 12 @@ -91,7 +92,7 @@ SYSTEM '' '' * [[_RED32]], [[_GREEN32]], [[_BLUE32]] * [[_PALETTECOLOR]] * [[HEX$ 32 Bit Values]] -* [[SAVEIMAGE]] {{text|(bitmap creator)}} +* [[SAVEIMAGE]] * [http://www.w3schools.com/html/html_colornames.asp Hexadecimal Color Values] diff --git a/internal/help/_RGBA.txt b/internal/help/_RGBA.txt index db19fbf6b..1bb33595d 100644 --- a/internal/help/_RGBA.txt +++ b/internal/help/_RGBA.txt @@ -1,25 +1,26 @@ {{DISPLAYTITLE:_RGBA}} -The [[_RGBA]] function returns the closest palette index OR the 32 bit [[LONG]] color value in 32 bit screens. +The [[_RGBA]] function returns the closest palette index (legacy SCREEN modes) OR the 32-bit [[LONG]] color value (32-bit screens). {{PageSyntax}} -:colorindex~& = '''_RGBA('''{{Parameter|red}}, {{Parameter|green}}, {{Parameter|blue}}, {{Parameter|alpha}}[, {{Parameter|image_handle}}]''')''' +: {{Parameter|colorIndex~&}} = [[_RGBA]]({{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}, {{Parameter|alpha&}}[, {{Parameter|imageHandle&}}]''')''' -* The value returned is either the closest color attribute number or a 32 bit [[_UNSIGNED]] [[LONG]] color value. -* '''Return variable types MUST be [[LONG]] or redulting color may lose the [[_BLUE]] value!'''' +* The value returned is either the closest color attribute number or a 32-bit [[_UNSIGNED]] [[LONG]] color value. +* '''Return variable types must be [[LONG]] or the resulting color may lose the [[_BLUE]] value.''' * {{Parameter|red&}} specifies the red component intensity from 0 to 255. * {{Parameter|green&}} specifies the green component intensity from 0 to 255. * {{Parameter|blue&}} specifies the blue component intensity from 0 to 255. -* The [[_ALPHA|''alpha'']] value can be set to make the color transparent(0), opaque(255) or somewhere in between. +* The [[_ALPHA|''alpha&'']] value can be set to make the color transparent (0), opaque (255) or somewhere in between. * Parameter values outside of the 0 to 255 range are clipped. -* Returns [[LONG]] 32 bit hexadecimal values from '''&H00{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with varying [[_ALPHA]] transparency. -* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]](colorvalue&), 3) to place 3 colors. -* If the ''image_handle'' is omitted the image is assumed to be the current [[_DEST|destination]] or [[SCREEN]] page. +* Returns [[LONG]] 32-bit hexadecimal values from '''&H00{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with varying [[_ALPHA]] transparency. +* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]]({{Parameter|colorIndex~&}}), 3) to place 3 colors. +* If {{Parameter|imageHandle&}} is omitted, the image is assumed to be the current [[_DEST|destination]] or [[SCREEN]] page. * Allows the blending of pixel colors red, green and blue to create any of 16 million colors. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* '''NOTE: Default 32-bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' +{{PageExamples}} ''Example:'' Setting a font's background color alpha to clear to overlay a second text color. {{CodeStart}} '' '' scrn& = {{Cl|_NEWIMAGE}}(400, 400, 32) @@ -44,7 +45,7 @@ Y% = 20 * [[_LOADIMAGE]] * [[_PRINTSTRING]] * [[HEX$ 32 Bit Values]], [[POINT]] -* [[SAVEIMAGE]] {{text|(bitmap creator)}} +* [[SAVEIMAGE]] * [http://www.w3schools.com/html/html_colornames.asp Hexadecimal Color Values] diff --git a/internal/help/_RGBA32.txt b/internal/help/_RGBA32.txt index 17b149458..4a53232dd 100644 --- a/internal/help/_RGBA32.txt +++ b/internal/help/_RGBA32.txt @@ -1,37 +1,38 @@ {{DISPLAYTITLE:_RGBA32}} -The [[_RGBA32]] function ALWAYS returns the 32-bit ''RGBA'' color value with specified red, green, blue and alpha component intensities. +The [[_RGBA32]] function returns the 32-bit ''RGBA'' color value with the specified red, green, blue and alpha component intensities. {{PageSyntax}} -:color32value~& = '''_RGBA32('''{{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}, {{Parameter|alpha&}}''')''' +: {{Parameter|color32value~&}} = [[_RGBA32]]({{Parameter|red&}}, {{Parameter|green&}}, {{Parameter|blue&}}, {{Parameter|alpha&}}) {{PageDescription}} -* The value returned is ALWAYS a 32 bit [[_UNSIGNED]] [[LONG]] color value. -* '''Return variable types MUST be [[LONG]] or resulting color may lose the [[_BLUE]] value!''' +* The value returned is a 32-bit [[_UNSIGNED]] [[LONG]] color value. +* '''Return variable types must be [[LONG]] or resulting color may lose the [[_BLUE]] value.''' * {{Parameter|red&}} specifies the red component intensity from 0 to 255. * {{Parameter|green&}} specifies the green component intensity from 0 to 255. * {{Parameter|blue&}} specifies the blue component intensity from 0 to 255. * {{Parameter|alpha&}} specifies the [[_ALPHA|''alpha'']] component transparency value from 0 (fully transparent) to 255 (opaque). * Alpha or intensity values outside of the valid range of 0 to 255 are clipped. -* Returns [[LONG]] 32 bit hexadecimal values from '''&H00{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with varying [[_ALPHA]] transparency. -* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]](colorvalue&), 3) to place 3 colors. -* '''NOTE: Default 32 bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0)! Use [[CLS]] to make the black opaque!''' +* Returns [[LONG]] 32-bit hexadecimal values from '''&H00{{text|00|red}}{{text|00|green}}{{text|00|blue}}''' to '''&HFF{{text|FF|red}}{{text|FF|green}}{{text|FF|blue}}''' with varying [[_ALPHA]] transparency. +* When [[LONG]] values are [[PUT]] to file, the ARGB values become BGRA. Use [[LEFT$]]([[MKL$]]({{Parameter|color32value~&}}), 3) to place 3 colors. +* '''NOTE: Default 32-bit backgrounds are clear black or [[_RGBA]](0, 0, 0, 0). Use [[CLS]] to make the black opaque.''' -''Example:'' Changing the [[ALPHA]] value to fade an image in and out using a 32 bit PNG image! +{{PageExamples}} +''Example:'' Changing the [[ALPHA]] value to fade an image in and out using a 32 bit PNG image. {{CodeStart}} '' '' {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(600, 400, 32) -img& = {{Cl|_LOADIMAGE}}("qb64.png") 'use any 24/32 bit image -'//Turn off auto display +img& = {{Cl|_LOADIMAGE}}("qb64_trans.png") 'from http://www.qb64.net/qb64_trans.png (or use any 24/32 bit image) +'Turn off auto display {{Cl|_DISPLAY}} ' Fade in {{Cl|FOR...NEXT|FOR}} i% = 255 {{Cl|TO}} 0 {{Cl|STEP}} -5 {{Cl|_LIMIT}} 20 'control fade speed {{Cl|_PUTIMAGE}} (0, 0)-(600, 400), img& - {{Cl|LINE}} (0, 0)-(600, 400), {{Cl|_RGBA}}(0, 0, 0, i%), BF 'increase black box transparency + {{Cl|LINE}} (0, 0)-(600, 400), {{Cl|_RGBA}}(0, 0, 0, i%), BF 'decrease black box transparency {{Cl|_DISPLAY}} {{Cl|NEXT}} @@ -39,20 +40,19 @@ img& = {{Cl|_LOADIMAGE}}("qb64.png") 'use any 24/32 bit image {{Cl|FOR...NEXT|FOR}} i% = 0 {{Cl|TO}} 255 {{Cl|STEP}} 5 {{Cl|_LIMIT}} 20 'control fade speed {{Cl|_PUTIMAGE}} (0, 0)-(600, 400), img& - {{Cl|LINE}} (0, 0)-(600, 400), {{Cl|_RGBA}}(0, 0, 0, i%), BF 'decrease black box transparency + {{Cl|LINE}} (0, 0)-(600, 400), {{Cl|_RGBA}}(0, 0, 0, i%), BF 'increase black box transparency {{Cl|_DISPLAY}} {{Cl|NEXT}} {{Cl|END}} '' '' {{CodeEnd}} {{small|Code by Unseen Machine}} -:''Note:'' The QB64.PNG bee image used is available at the top of the QB64 forum: http://www.qb64.net/forum/index.php {{PageSeeAlso}} * [[_RGB32]], [[_RGBA]], [[_RGB]] * [[_RED32]], [[_GREEN32]], [[_BLUE32]] * [[HEX$ 32 Bit Values]], [[POINT]] -* [[SAVEIMAGE]] {{text|(bitmap creator)}} +* [[SAVEIMAGE]] * [http://www.w3schools.com/html/html_colornames.asp Hexadecimal Color Values] diff --git a/internal/help/_ROUND.txt b/internal/help/_ROUND.txt index 7b7712614..49661ecea 100644 --- a/internal/help/_ROUND.txt +++ b/internal/help/_ROUND.txt @@ -1,15 +1,15 @@ {{DISPLAYTITLE:_ROUND}} -The [[_ROUND]] function rounds to the closest EVEN [[INTEGER]], [[LONG]] or [[_INTEGER64]] numerical value. +The [[_ROUND]] function rounds to the closest even [[INTEGER]], [[LONG]] or [[_INTEGER64]] numerical value. {{PageSyntax}} -:: value = _ROUND ({{Parameter|number}}) +: {{Parameter|value}} = [[_ROUND]]({{Parameter|number}}) {{PageDescription}} * Can round [[SINGLE]], [[DOUBLE]] or [[_FLOAT]] floating decimal point parameter values. * Can be used when numerical values exceed the limits of [[CINT]] or [[CLNG]]. -* Rounding is done to the closest even [[INTEGER|integer]] value. The same as Qbasic does with [[\|integer division]]. +* Rounding is done to the closest even [[INTEGER|integer]] value. The same as QBasic does with [[\|integer division]]. ''Example:'' Displays how QB64 rounds to the closest even integer value. diff --git a/internal/help/_SCREENCLICK.txt b/internal/help/_SCREENCLICK.txt index 98e64fe50..e2351f6a5 100644 --- a/internal/help/_SCREENCLICK.txt +++ b/internal/help/_SCREENCLICK.txt @@ -3,20 +3,21 @@ The [[_SCREENCLICK]] statement simulates clicking on a pixel coordinate on the d {{PageSyntax}} -::: [[_SCREENCLICK]] {{Parameter|column%}}''',''' {{Parameter|row%}} +: [[_SCREENCLICK]] {{Parameter|column%}}, {{Parameter|row%}}[, {{Parameter|button%}}] {{PageDescription}} * {{Parameter|column%}} is the horizontal pixel coordinate position on the screen. * {{Parameter|row%}} is the vertical pixel coordinate position on the screen. -* Coordinates can range from 0 to the [[_WIDTH]] and [[_HEIGHT]] of the image handle returned by the [[_SCREENIMAGE]] function. The desktop image can be used to map the coordinates required. +* Optional {{Parameter|button%}} can be used to specify left button (1, default), right button (2) or middle button (3) (available with '''build 20170924/68'''). +* Coordinates can range from 0 to the [[_DESKTOPWIDTH]] and [[_DESKTOPHEIGHT]]. The desktop image acquired by [[_SCREENIMAGE]] can be used to map the coordinates required. * [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] {{PageSeeAlso}} - * [[_SCREENIMAGE]], [[_SCREENPRINT]] * [[_SCREENMOVE]], [[_SCREENX]], [[_SCREENY]] +* [[_DESKTOPWIDTH]], [[_DESKTOPHEIGHT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SCREENEXISTS.txt b/internal/help/_SCREENEXISTS.txt index 5f961acc3..6f672e264 100644 --- a/internal/help/_SCREENEXISTS.txt +++ b/internal/help/_SCREENEXISTS.txt @@ -1,16 +1,18 @@ {{DISPLAYTITLE:_SCREENEXISTS}} -The [[_SCREENEXISTS]] function returns a -1 value once a screen has been created. +The [[_SCREENEXISTS]] function returns true (-1) once a screen has been created. {{PageSyntax}} -::: screenready = '''_SCREENEXISTS''' +: {{Parameter|screenReady%%}} = [[_SCREENEXISTS]] {{PageDescription}} -* Function returns a true value once a program screen is available to use or change. -* Avoids program errors or omissions because a screen was not ready for input or alterations. +* Function returns true (-1) once a program screen is available to use or change. +* Can be used to avoid program errors because a screen was not ready for input or alterations. +** Use before [[_TITLE]], [[_SCREENMOVE]] and other functions that require the output window to have been created. +{{PageExamples}} ''Example:'' The loop waits until the screen exists to add the title. {{CodeStart}} '' '' {{Cl|SCREEN}} 12 diff --git a/internal/help/_SCREENICON.txt b/internal/help/_SCREENICON.txt index 2eaa8657a..066c704e0 100644 --- a/internal/help/_SCREENICON.txt +++ b/internal/help/_SCREENICON.txt @@ -1,17 +1,20 @@ {{DISPLAYTITLE:_SCREENICON}} -The '''_SCREENICON''' statement can be used to minimize the main program window to the taskbar. +The [[_SCREENICON]] statement can be used to minimize the main program window to the taskbar. {{PageSyntax}} -::: [[_SCREENICON]] +: [[_SCREENICON]] -* Use _SCREENICON to minimize the main program window to the taskbar. -* Keyword is only supported in QB64-GL version. SDL doesn't support this command. +{{PageDescription}} +* Use [[_SCREENICON]] to minimize the main program window to the taskbar. -''See also:'' +==Availability== +* '''Version 1.000 and up'''. + +{{PageSeeAlso}} * [[$SCREENHIDE]], [[$SCREENSHOW]], [[$CONSOLE]] (QB64 [[Metacommand]]s) * [[_SCREENHIDE]], [[_SCREENSHOW]], [[_CONSOLE]] * [[_SCREENICON (function)]] diff --git a/internal/help/_SCREENICON_(function).txt b/internal/help/_SCREENICON_(function).txt index d470ed9c6..7d8298539 100644 --- a/internal/help/_SCREENICON_(function).txt +++ b/internal/help/_SCREENICON_(function).txt @@ -1,14 +1,14 @@ {{DISPLAYTITLE:_SCREENICON (function)}} -The _SCREENICON function returns -1 or 0 to indicate if the window has been minimized to an icon on the taskbar. +The [[_SCREENICON (function)|_SCREENICON]] function returns true (-1) or false (0) to indicate if the window has been minimized to an icon on the taskbar. {{PageSyntax}} -::: minimized = '''_SCREENICON +: {{Parameter|isMinimized%%}} = [[_SCREENICON]] {{PageDescription}} -* The function indicates -1 when the program is minimized to the task bar and 0 when not. +* The function returns true (-1) when the program is minimized to the task bar and false (0) when not. {{PageSeeAlso}} diff --git a/internal/help/_SCREENIMAGE.txt b/internal/help/_SCREENIMAGE.txt index faf7fddcc..999d4eb9d 100644 --- a/internal/help/_SCREENIMAGE.txt +++ b/internal/help/_SCREENIMAGE.txt @@ -1,42 +1,38 @@ {{DISPLAYTITLE:_SCREENIMAGE}} -The {{KW|_SCREENIMAGE}} function stores the current desktop image or a portion of it and returns a handle value to reference. +The [[_SCREENIMAGE]] function stores the current desktop image or a portion of it and returns an image handle. {{PageSyntax}} -:: handle& = [[_SCREENIMAGE[]](''column1'', ''row1'', ''column2'', ''row2'')] +: {{Parameter|imageHandle&}} = [[_SCREENIMAGE]]({{Parameter|column1}}, {{Parameter|row1}}, {{Parameter|column2}}, {{Parameter|row2}})] {{PageDescription}} -* The handle& value is the desktop image reference in memory of the present user's desktop. -* The optional screen ''column'' and ''row'' positions can be used to get only a portion of the desktop image. +* {{Parameter|imageHandle&}} is the handle to the new image in memory that will contain the desktop screenshot. +* The optional screen {{Parameter|column}} and {{Parameter|row}} positions can be used to get only a portion of the desktop image. * The desktop image or partial image is always a 32-bit image. -* The current screen resolution or width-to-height aspect ratio can be measured using the handle with [[_WIDTH (function)|_WIDTH]] and [[_HEIGHT]]. -* Can be used to take screen shots of the desktop or used with [[_PRINTIMAGE]] to print them. -* It is IMPORTANT to free unused or uneeded image handles with [[_FREEIMAGE]] to prevent memory overflow errors! -* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] +* The current screen resolution or width-to-height aspect ratio can be obtained with [[_DESKTOPWIDTH]] and [[_DESKTOPHEIGHT]]. +* Can be used to take screenshots of the desktop or used with [[_PRINTIMAGE]] to print them. +* It is important to free unused or uneeded image handles with [[_FREEIMAGE]] to prevent memory overflow errors. +* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword not Supported in Linux or MAC versions]] +{{PageExamples}} ''Example:'' Determining the present screen resolution of user's PC for a screensaver program. {{CodeStart}} desktop& = {{Cl|_SCREENIMAGE}} MaxScreenX& = {{Cl|_WIDTH (function)|_WIDTH}}(desktop&) MaxScreenY& = {{Cl|_HEIGHT}}(desktop&) {{Cl|_FREEIMAGE}} desktop& 'free image after measuring screen(it is not displayed) - {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(MaxScreenX&, MaxScreenY&, 256) 'program window is sized to fit '' '' + {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(MaxScreenX&, MaxScreenY&, 256) 'program window is sized to fit {{Cl|_SCREENMOVE}} _MIDDLE {{CodeEnd}} - -''Screen image savers:'' - -*{{KW|SAVEIMAGE}} (QB64 Image to Bitmap SUB by Galleon) - -*{{KW|Program ScreenShots}} (Member program for legacy screen modes) - -* {{KW|ThirtyTwoBit SUB}} (QB64 Image area to bitmap) - -* [[SaveIcon32]] {{text|(converts any image to icon)}} +===Sample code to save images to disk=== +*[[SAVEIMAGE]] +*[[Program ScreenShots]] (member-contributed program for legacy screen modes) +* [[ThirtyTwoBit SUB]] +* [[SaveIcon32]] @@ -44,8 +40,8 @@ The {{KW|_SCREENIMAGE}} function stores the current desktop image or a portion o * [[_SCREENCLICK]], [[_SCREENPRINT]] * [[_SCREENMOVE]], [[_SCREENX]], [[_SCREENY]] * [[_WIDTH (function)|_WIDTH]], [[_HEIGHT]] +* [[_DESKTOPWIDTH]], [[_DESKTOPHEIGHT]] * [[_FULLSCREEN]], [[_PRINTIMAGE]] -* [[SAVEIMAGE]] {{text|(save image to bitmap program)}} * [[Screen Saver Programs]] * [[Bitmaps]], [[Icons and Cursors]] * [[Hardware images]] diff --git a/internal/help/_SCREENMOVE.txt b/internal/help/_SCREENMOVE.txt index 435cd2024..6382c7ac8 100644 --- a/internal/help/_SCREENMOVE.txt +++ b/internal/help/_SCREENMOVE.txt @@ -1,32 +1,32 @@ {{DISPLAYTITLE:_SCREENMOVE}} -The '''_SCREENMOVE''' statement positions the program window on the desktop using designated coordinates or the _MIDDLE function. +The [[_SCREENMOVE]] statement positions the program window on the desktop using designated coordinates. {{PageSyntax}} -:: '''_SCREENMOVE'''{''column&'', ''row&'')|_MIDDLE} +: [[_SCREENMOVE]] {{{Parameter|column&}}, {{Parameter|row&}}|_MIDDLE} {{Parameters}} -* Positions the program window on the desktop using the ''column'' and ''row'' pixel coordinates for the upper left corner. -* '''_MIDDLE''' can be used instead to automatically center the program window's position on the desktop in any screen resolution. +* Positions the program window on the desktop using the {{Parameter|column&}} and {{Parameter|row&}} pixel coordinates for the upper left corner. +* '''_MIDDLE''' can be used instead to automatically center the program window on the desktop, in any screen resolution. -''Usage:'' +{{PageDescription}} * The program's [[SCREEN]] dimensions may influence the desktop position that can be used to keep the entire window on the screen. -* Use [[_SCREENIMAGE]] handle with [[_WIDTH (function)|_WIDTH]] and [[_HEIGHT]] to find the current Windows desktop resolution to place the program's window. -* On dual monitors a negative ''column'' position or a value greater than the main screen width can be used to position a window left or right. -* '''A small delay may be necessary when a program first starts up to properly orient the screen on the desktop properly!''' -* '''[[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]]''' +* Use [[_DESKTOPWIDTH]] and [[_DESKTOPHEIGHT]] to find the current desktop resolution to place the program's window. +* On dual monitors a negative {{Parameter|column&}} position or a value greater than the main screen width can be used to position a window in another monitor. +* '''A small delay may be necessary when a program first starts up to properly orient the screen on the desktop properly.''' See [[_SCREENEXISTS]]. +* '''[[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword not supported in Linux or MAC versions]]''' -''Example 1:'' Calculating the border and header offsets by comparing a coordinate move with MIDDLE by using trial and error. -{{CodeStart}} '' '' -user& = {{Cl|_SCREENIMAGE}} -userwidth& = {{Cl|_WIDTH}}(user&): userheight& = {{Cl|_HEIGHT}}(user&) 'get current screen resolution +{{PageExamples}} +''Example 1:'' Calculating the border and header offsets by comparing a coordinate move with _MIDDLE by using trial and error. +{{CodeStart}} +userwidth& = {{Cl|_DESKTOPWIDTH}}: userheight& = {{Cl|_DESKTOPHEIGHT}} 'get current screen resolution {{Cl|SCREEN}} {{Cl|_NEWIMAGE}}(800, 600, 256) -scrnwidth& = {{Cl|_WIDTH}}: scrnheight& = {{Cl|_HEIGHT}} 'get the center of the program screen +scrnwidth& = {{Cl|_WIDTH}}: scrnheight& = {{Cl|_HEIGHT}} 'get the dimensions of the program screen -{{Cl|_SCREENMOVE}} (userwidth& \ 2 - scrnwidth& \ 2) - 3, (userheight \ 2 - scrnheight& \ 2) - 29 +{{Cl|_SCREENMOVE}} (userwidth& \ 2 - scrnwidth& \ 2) - 3, (userheight& \ 2 - scrnheight& \ 2) - 29 {{Cl|_DELAY}} 4 {{Cl|_SCREENMOVE}} _MIDDLE 'check centering @@ -36,10 +36,9 @@ scrnwidth& = {{Cl|_WIDTH}}: scrnheight& = {{Cl|_HEIGHT}} 'get the cente ''Example 2:'' Moving a program window to a second monitor positioned to the right of the main desktop. -{{CodeStart}} '' '' -img& = {{Cl|_SCREENIMAGE}} -wide& = {{Cl|_WIDTH (function)|_WIDTH}}(img&) -high& = {{Cl|_HEIGHT}}(img&) +{{CodeStart}} +wide& = {{Cl|_DESKTOPWIDTH}} +high& = {{Cl|_DESKTOPHEIGHT}} {{Cl|PRINT}} wide&; "X"; high& @@ -53,26 +52,16 @@ high2& = {{Cl|_HEIGHT}}(img2&) {{Cl|_DELAY}} 4 {{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}} 'moves program back to main monitor 1 '' '' {{CodeEnd}} -: ''Notes:'' [[_SCREENIMAGE]] only returns the resolution of the main desktop. Change the [[_SCREENMOVE]] column to negative for a left monitor. +: ''Notes:'' Change the [[_SCREENMOVE]] column to negative for a left monitor. -{{WhiteStart}} '''Setting up dual monitors''' - - 1) Turn off the computer and attach the second monitor to the computer - 2) Restart computer and right click an empty desktop area and click ''Properties''. - 3) In the Settings tab set the position of the monitor numbered 2 to left or right. - 4) Set the resolution to match the main desktop resolution as closely as possible. - 5) Save the settings before the prompt window times out. -{{WhiteEnd}} -<center>[http://www.geeks.com/techtips/2005/techtips-AUG18-05.htm Dual monitor setup]</center> +<center>'''[[_FULLSCREEN]] works in the primary monitor and may push all running programs to a monitor on the right.'''</center> -<center>'''[[_FULLSCREEN]] works in the primary monitor and may push all running programs to a monitor on the right!'''</center> - - -''See also:'' +{{PageSeeAlso}} * [[_SCREENX]], [[_SCREENY]] -* [[_SCREENIMAGE]] +* [[_SCREENIMAGE]], [[_DESKTOPWIDTH]], [[_DESKTOPHEIGHT]] * [[_SCREENPRINT]] +* [[_SCREENEXISTS]] * [[_NEWIMAGE]], [[SCREEN (statement)]] diff --git a/internal/help/_SCREENPRINT.txt b/internal/help/_SCREENPRINT.txt index 7d431734e..75fbe6de0 100644 --- a/internal/help/_SCREENPRINT.txt +++ b/internal/help/_SCREENPRINT.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_SCREENPRINT}} -The [[_SCREENPRINT]] statement simulates typing text into a Windows focused program using the keyboard. +The [[_SCREENPRINT]] statement simulates typing text into a Windows focused program. {{PageSyntax}} -::: [[_SCREENPRINT]] {{Parameter|text$}} +: [[_SCREENPRINT]] {{Parameter|text$}} {{PageDescription}} -* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword Not Supported in Linux or MAC versions]] -* {{Parameter|text$}} is the text to be typed into a "focused" program's text entry area one character at a time. -* Set the "focus" to a desktop program by using the [[_SCREENIMAGE]] handle as the [[_SOURCE]]. Use the image to map the area. +* [[Keywords_currently_not_supported_by_QB64#Keywords_Not_Supported_in_Linux_or_MAC_OSX_versions|Keyword not supported in Linux or MAC versions]] +* {{Parameter|text$}} is the text to be typed into a focused program's text entry area, one character at a time. +* Set the focus to a desktop program by using the [[_SCREENIMAGE]] handle as the [[_SOURCE]]. Use the image to map the desired area. * [[_SCREENCLICK]] can also be used to set the focus to a program's text entry area on the desktop. -*'''Note: If the focus is not set correctly, the text may be printed to the QB64 IDE or not printed at all!''' -* Program Ctrl + letter key shortcuts can be simulated using the appropriate [[ASCII]] Control character codes 1 to 26 shown below: +*'''Note: If the focus is not set correctly, the text may be printed to the QB64 IDE, if open, or not printed at all.''' +* Ctrl + letter key shortcuts can be simulated using the appropriate [[ASCII]] Control character codes 1 to 26 shown below: {{WhiteStart}} CTRL + A = CHR$(1) ☺ StartHeader (SOH) CTRL + B = CHR$(2) ☻ StartText (STX) CTRL + C = CHR$(3) ♥ EndText (ETX) CTRL + D = CHR$(4) ♦ EndOfTransmit (EOT) CTRL + E = CHR$(5) ♣ Enquiry (ENQ) CTRL + F = CHR$(6) ♠ Acknowledge (ACK) @@ -28,7 +28,9 @@ The [[_SCREENPRINT]] statement simulates typing text into a Windows focused prog CTRL + Y = CHR$(25) ↓ EndMedium (EM) CTRL + Z = CHR$(26) → End Of File(SUB) (EOF) {{WhiteEnd}} -''Example:'' Printing text into a Windows text editor (Notepad) and copying to the clipboard. MAY NOT WORK ON ALL SYSTEMS! + +{{PageExamples}} +''Example:'' Printing text into a Windows text editor (Notepad) and copying to the clipboard. May not work on all systems. {{CodeStart}} '' '' {{Cl|DEFLNG}} A-Z {{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 32) diff --git a/internal/help/_SCREENSHOW.txt b/internal/help/_SCREENSHOW.txt index 02f0548f8..04a6227e4 100644 --- a/internal/help/_SCREENSHOW.txt +++ b/internal/help/_SCREENSHOW.txt @@ -1,16 +1,16 @@ {{DISPLAYTITLE:_SCREENSHOW}} -The '''_SCREENSHOW''' statement can be used to display the main program window in a section of code. +The [[_SCREENSHOW]] statement can be used to display the main program window in a section of code. {{PageSyntax}} -::: [[_SCREENSHOW]] +: [[_SCREENSHOW]] +{{PageDescription}} * [[_SCREENHIDE]] or [[$SCREENHIDE]] must be used before _SCREENSHOW or [[$SCREENSHOW]] can be used! -''See also:'' - +{{PageSeeAlso}} * [[$SCREENHIDE]], [[$SCREENSHOW]], [[$CONSOLE]] (QB64 [[Metacommand]]s) * [[_SCREENHIDE]], [[_CONSOLE]] diff --git a/internal/help/_SCREENX.txt b/internal/help/_SCREENX.txt index be06800f8..3cc2f15c4 100644 --- a/internal/help/_SCREENX.txt +++ b/internal/help/_SCREENX.txt @@ -1,25 +1,25 @@ {{DISPLAYTITLE:_SCREENX}} -The '''_SCREENX''' function returns the current column pixel coordinate of the program window on the desktop. +The [[_SCREENX]] function returns the current column pixel coordinate of the program window on the desktop. {{PageSyntax}} -:: positionX& = [[_SCREENX]] +: {{Parameter|positionX&}} = [[_SCREENX]] +{{PageDescription}} * Function returns the current program window's upper left corner column position on the desktop. -* Use [[_SCREENIMAGE]] to find the current user's Windows desktop resolution to adjust the position with [[_SCREENMOVE]]. +* Use [[_DESKTOPWIDTH]] and [[_DESKTOPHEIGHT]] to find the current Windows desktop resolution to adjust the position with [[_SCREENMOVE]]. +{{PageExamples}} ''Example:'' Clicks and opens program window header menu: {{CodeStart}}{{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}} - {{Cl|_SCREENCLICK}} {{Cl|_SCREENX}} + 10, {{Cl|_SCREENY}} + 10 - -{{Cl|PRINT}} "Hello window!" '' '' +{{Cl|PRINT}} "Hello window!" {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_SCREENIMAGE]] * [[_SCREENCLICK]] * [[_SCREENPRINT]] diff --git a/internal/help/_SCREENY.txt b/internal/help/_SCREENY.txt index 972a501b9..767527055 100644 --- a/internal/help/_SCREENY.txt +++ b/internal/help/_SCREENY.txt @@ -1,25 +1,25 @@ {{DISPLAYTITLE:_SCREENY}} -The '''_SCREENY''' function returns the current row pixel coordinate of the program window on the desktop. +The [[_SCREENY]] function returns the current row pixel coordinate of the program window on the desktop. {{PageSyntax}} -:: positionY& = [[_SCREENY]] +: {{Parameter|positionY&}} = [[_SCREENY]] +{{PageDescription}} * Function returns the current program window's upper left corner row position on the desktop. -* Use [[_SCREENIMAGE]] to find the current user's Windows desktop resolution to adjust the position with [[_SCREENMOVE]]. +* Use [[_DESKTOPWIDTH]] and [[_DESKTOPHEIGHT]] to find the current user's Windows desktop resolution to adjust the position with [[_SCREENMOVE]]. +{{PageExamples}} ''Example:'' Clicks and opens program window header menu: {{CodeStart}}{{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}} - {{Cl|_SCREENCLICK}} {{Cl|_SCREENX}} + 10, {{Cl|_SCREENY}} + 10 - {{Cl|PRINT}} "Hello window!" '' '' {{CodeEnd}} -''See also:'' +{{PageSeeAlso}} * [[_SCREENIMAGE]] * [[_SCREENCLICK]] * [[_SCREENPRINT]] diff --git a/internal/help/_SETALPHA.txt b/internal/help/_SETALPHA.txt index faf32bbfc..01ffadf3d 100644 --- a/internal/help/_SETALPHA.txt +++ b/internal/help/_SETALPHA.txt @@ -1,36 +1,37 @@ {{DISPLAYTITLE:_SETALPHA}}{{DISPLAYTITLE:}} -The '''_SETALPHA''' statement sets the alpha channel transparency level of some or all of the pixels of an image. +The [[_SETALPHA]] statement sets the alpha channel transparency level of some or all of the pixels of an image. {{PageSyntax}} -::: '''_SETALPHA ''alpha&'''''[, ''colour1&''][ {{KW|TO}} ''colour2&''] [, ''imageHandle&''] +: [[_SETALPHA]] {{Parameter|alpha&}}[, {{Parameter|color1&}}][ [[TO]] {{Parameter|colour2&}}] [, {{Parameter|imageHandle&}}] {{Parameters}} * {{Parameter|alpha&}} is the new alpha level to set, ranging from 0 (transparent) to 255 (opaque). -* ''co1or&'' designates the 32 bit [[LONG]] color value or range of color values ''c1&'' TO ''c2&'' to set the transparency. +* {{Parameter|color1&}} designates the 32-bit [[LONG]] color value or range of color values {{Parameter|color1&}} TO {{Parameter|colour2&}} to set the transparency. * If no color value or range of colors is given, the entire image's alpha is changed, including any [[_CLEARCOLOR]] settings. * If {{Parameter|imageHandle&}} is omitted, it is assumed to be the current write page or [[_DEST|destination]] image. -''Usage:'' +{{PageDescription}} * In the first syntax, the alpha level of all pixels is set to {{Parameter|alpha&}}. -* In the second syntax, the alpha level of all pixels matching the color {{Parameter|c&}} is set to {{Parameter|alpha&}}. -* In the third syntax, the alpha level of all pixels with red, green, blue and alpha channels in the range [{{Parameter|c1&}} TO {{Parameter|c2&}}] are set. -* The [[_ALPHA]] setting makes a 32 bit color transparent, opaque or something in between. Zero is clear and 255 totally blocks underlying images. Use it to see through backgrounds or image colors. +* In the second syntax, the alpha level of all pixels matching the color {{Parameter|color1&}} is set to {{Parameter|alpha&}}. +* In the third syntax, the alpha level of all pixels with red, green, blue and alpha channels in the range [{{Parameter|color1&}} TO {{Parameter|color2&}}] are set. +* The [[_ALPHA]] setting makes a 32-bit color transparent, opaque or something in between. Zero is clear and 255 totally blocks underlying images. Use it to see through backgrounds or image colors. * If {{Parameter|alpha&}} is outside that range, an [[ERROR Codes|illegal function call]] error will occur. * If the image specified by {{Parameter|imageHandle&}} uses a palette, an [[ERROR Codes|invalid handle]] error will occur. * If {{Parameter|imageHandle&}} is an invalid handle, an [[ERROR Codes|illegal function call]] error will occur. -* '''NOTE: 32 bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque!''' +* '''NOTE: 32-bit [[_NEWIMAGE]] screen page backgrounds are transparent black or [[_ALPHA]] 0. Use [[_DONTBLEND]] or [[CLS]] for opaque.''' +{{PageExamples}} ''Example:'' Using a _SETALPHA color range to fade an image in and out while not affecting the transparent white background. {{CodeStart}} '' '' main = {{Cl|_NEWIMAGE}}(640, 480, 32) {{Cl|SCREEN}} main {{Cl|_SCREENMOVE}} {{Cl|_SCREENMOVE|_MIDDLE}} -Image1& = {{Cl|_LOADIMAGE}}("qb64bee.png") '<<< PNG file with white background to hide +Image1& = {{Cl|_LOADIMAGE}}("qb64_trans.png") '<<< PNG file with white background to hide {{Cl|_SOURCE}} Image1& clr~& = {{Cl|POINT}}(0, 0) 'find background color of image {{Cl|_CLEARCOLOR}} clr~&, Image1& 'set background color as transparent @@ -51,14 +52,14 @@ DO {{Cl|_DISPLAY}} {{Cl|LOOP}} {{Cl|UNTIL}} a& = 0 '' '' {{CodeEnd}} -: ''Explanation:'' The [[POINT]] value minus [[_RGBA]](1, 1, 1, 0) subtracts a small amount from the bright white color value so that the top [[_SETALPHA]] color range will not affect the [[_CLEARCOLOR]] transparency of the bright white PNG background. [https://dl.dropbox.com/u/8440706/QB64bee.png QB64bee.png]. +: ''Explanation:'' The [[POINT]] value minus [[_RGBA]](1, 1, 1, 0) subtracts a small amount from the bright white color value so that the top [[_SETALPHA]] color range will not affect the [[_CLEARCOLOR]] transparency of the bright white PNG background. [http://www.qb64.net/qb64_trans.png qb64_trans.png]. {{PageSeeAlso}} -* [[_ALPHA]], [[_ALPHA32]] {{text|(read transparency level)}} -* [[_RGBA]], [[_RGBA32]] {{text|(set color levels and alpha)}} -* [[_CLEARCOLOR]] {{text|(sets a transparent color)}} -* [[_CLEARCOLOR (function)]] {{text|(finds transparent color)}} +* [[_ALPHA]], [[_ALPHA32]] +* [[_RGBA]], [[_RGBA32]] +* [[_CLEARCOLOR]] +* [[_CLEARCOLOR (function)]] * [[_BLEND]], [[_DONTBLEND]] * [[COLOR]], [[Images]] diff --git a/internal/help/_SHELLHIDE.txt b/internal/help/_SHELLHIDE.txt index 1f6e00061..5b8c84159 100644 --- a/internal/help/_SHELLHIDE.txt +++ b/internal/help/_SHELLHIDE.txt @@ -1,21 +1,21 @@ {{DISPLAYTITLE:_SHELLHIDE}} -The '''_SHELLHIDE''' function hides the console window and returns any [[INTEGER]] code sent by [[END]] or [[SYSTEM]] when a program exits. +The [[_SHELLHIDE]] function hides the console window and returns any [[INTEGER]] code sent by [[END]] or [[SYSTEM]] when a program exits. {{PageSyntax}} - -::: return_code = '''_SHELLHIDE('''''command$''''')''' +: {{Parameter|returnCode%}} = [[_SHELLHIDE]]({{Parameter|externalCommand$}}) {{Parameters}} -* The literal or variable [[STRING]] ''command'' parameter can be any [[DOS]] command line or call to another program. +* The literal or variable [[STRING]] {{Parameter|externalCommand$}} parameter can be any external [[DOS|command line]] or call to another program. -''Usage:'' -* QB64 can now return codes sent by program modules when a specified code is added after [[END]] code% or [[SYSTEM]] code%. -* The code can verify that a previous SHELL command was executed. +{{PageDescription}} +* QB64 can return codes sent by program modules when a specified code is added after [[END]] or [[SYSTEM]]. +* The code can be used to verify that a previous SHELL command was executed. +{{PageExamples}} ''Example:'' Shelling to another QB64 program will return the exit code when one is set in the program that is run. {{CodeStart}} '' '' returncode% = {{Cl|_SHELLHIDE}}("DesktopSize") 'replace call with your program EXE @@ -27,7 +27,7 @@ returncode% = {{Cl|_SHELLHIDE}}("DesktopSize") 'replace call with your : ''Explanation:'' To set a program exit code use an [[INTEGER]] parameter value after [[END]] or [[SYSTEM]] in the called program. -''See also:'' +{{PageSeeAlso}} * [[SHELL (function)]] * [[SHELL]], [[_HIDE]] * [[_CONSOLE]], [[$CONSOLE]] diff --git a/internal/help/_SNDBAL.txt b/internal/help/_SNDBAL.txt index 81b856672..b98b7ae1b 100644 --- a/internal/help/_SNDBAL.txt +++ b/internal/help/_SNDBAL.txt @@ -3,37 +3,29 @@ The [[_SNDBAL]] statement attempts to set the balance or 3D position of a sound. {{PageSyntax}} -:::[[_SNDBAL]] {{Parameter|handle&}}[, {{Parameter|x!}}][, {{Parameter|y!}}][, {{Parameter|z!}}] +: [[_SNDBAL]] {{Parameter|handle&}}[, {{Parameter|x!}}][, {{Parameter|y!}}][, {{Parameter|z!}}][, {{Parameter|channel&}}]] + + +{{Parameters}} +* ''handle&'' is a valid sound handle created by the [[_SNDOPEN]] function. +* {{Parameter|x!}} distance values go from left (negative) to right (positive). +* {{Parameter|y!}} distance values go from below (negative) to above (positive). +* {{Parameter|z!}} distance values go from behind (negative) to in front (positive). +* {{Parameter|channel&}} value 1 denotes left (mono) and 2 denotes right (stereo) channel (beginning with '''build 20170811/60''') {{PageDescription}} *Attempts to position a sound in 3D space, or as close to it as the underlying software libraries allow. In some cases, this will be true 3D positioning, in others, a mere volume adjustment based on distance alone. -:::*x distance values go from left(negative) to right(positive). -:::*y distance values go from below(negative) to above(positive). -:::*z distance values go from behind(negative) to in front(positive). -*Omitted x, y or z {{KW|SINGLE}} values are set to 0. -*By setting the x value to -1 or 1 it plays the sound at full volume from the appropriate speaker. +*Omitted x!, y! or z! [[SINGLE]] values are set to 0 or not changed in '''build 20170811/60 onward'''. +*By setting the x! value to -1 or 1 it plays the sound at full volume from the appropriate speaker. *Sounds at a distance of 1 or -1 are played at full volume. Sounds further than a distance of 1000 cannot be heard. *The volume decreases linearly (at a constant gradient) over distance. Half volume = 500. -* Opened sound files must have the "VOL" capability to use this statement. -* The sound file should have the "SYNC" capability when more than one sound is being used at the same time! -* An "'''ILLEGAL FUNCTION CALL'''" error can occur if another sound is using the primary or same channel position. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +* An "'''Illegal Function Call'''" error can occur if another sound is using the primary or same channel position. +* Opened sound files must have the [[_SNDOPEN|"VOL"]] capability to use this statement in versions '''before build 20170811/60.''' {{PageExamples}} +''Example 1:'' {{CodeStart}} '' '' h& = {{Cl|_SNDOPEN}}("LOL.wav", "SYNC,VOL") {{Cl|_SNDBAL}} h&, 1 @@ -41,8 +33,69 @@ h& = {{Cl|_SNDOPEN}}("LOL.wav", "SYNC,VOL") {{CodeEnd}} +''Example:'' Loading a sound after '''build 20170811/60''' - no need to specify "sound capabilities" in [[_SNDOPEN]]. +{{CodeStart}} +s& = {{Cl|_SNDOPEN}}("song.ogg") +{{Cl|PRINT}} "{{Cl|READ}}Y"; s& +{{Cl|_SNDPLAY}} s& +{{Cl|_SNDLOOP}} s& + + +xleft = -1 +xright = 1 +DO + k$ = {{Cl|INKEY$}} + {{Cl|SELECT CASE}} k$ + {{Cl|CASE}} "f" + xleft = xleft - 0.1 + {{Cl|_SNDBAL}} s&, xleft, , , 1 + {{Cl|CASE}} "g" + xleft = xleft + 0.1 + {{Cl|_SNDBAL}} s&, xleft, , , 1 + {{Cl|CASE}} "h" + xright = xright - 0.1 + {{Cl|_SNDBAL}} s&, xright, , , 2 + {{Cl|CASE}} "j" + xright = xright + 0.1 + {{Cl|_SNDBAL}} s&, xright, , , 2 + {{Cl|CASE}} "n" + volume = volume - 0.1 + {{Cl|_SNDVOL}} s&, volume + {{Cl|CASE}} "m" + volume = volume + 0.1 + {{Cl|_SNDVOL}} s&, volume + {{Cl|CASE}} "p" + {{Cl|_SNDPAUSE}} s& + {{Cl|CASE}} " " + {{Cl|_SNDPLAY}} s& + {{Cl|CASE}} "i" + {{Cl|PRINT}} {{Cl|_SNDPLAYING}}(s&) + {{Cl|PRINT}} {{Cl|_SNDPAUSED}}(s&) + {{Cl|SLEEP}} + {{Cl|CASE}} "b" + {{Cl|_SNDSETPOS}} s&, 110 + {{Cl|CASE}} "l" + {{Cl|_SNDLIMIT}} s&, 10 + {{Cl|PRINT}} "LIM" + {{Cl|SLEEP}} + {{Cl|CASE}} "k" + {{Cl|_SNDSTOP}} s& + {{Cl|CASE}} "c" + {{Cl|_SNDCLOSE}} s& + {{Cl|SLEEP}} + s2& = {{Cl|_SNDOPEN}}("song.ogg") + {{Cl|CASE}} "d" + s2& = {{Cl|_SNDCOPY}}(s&) + {{Cl|_SNDPLAY}} s2& + {{Cl|END SELECT}} + {{Cl|LOCATE}} 1, 1 + {{Cl|PRINT}} xleft, xright, volume, {{Cl|_SNDGETPOS}}(s&); " " +LOOP +{{CodeEnd}}{{small|Code by Johny B}} + + {{PageSeeAlso}} -*{{KW|_SNDOPEN}}, {{KW|_SNDVOL}}, {{KW|_SNDLIMIT}} +*[[_SNDOPEN]], [[_SNDVOL]], [[_SNDLIMIT]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SNDCLOSE.txt b/internal/help/_SNDCLOSE.txt index 2e84d0e4a..ca5c3b5d1 100644 --- a/internal/help/_SNDCLOSE.txt +++ b/internal/help/_SNDCLOSE.txt @@ -3,24 +3,17 @@ The [[_SNDCLOSE]] statement frees and unloads an open sound using a [[_SNDOPEN]] {{PageSyntax}} -::: [[_SNDCLOSE]] {{Parameter|handle&}} +: [[_SNDCLOSE]] {{Parameter|handle&}} {{PageDescription}} -* If the sound is still playing, it will be freed after it finishes automatically. -* Closing a looping/paused/etc. sound will mean it is never freed until the QB64 program terminates. -* Non-SYNC sounds must be closed before another Non-SYNC sound can be opened. -* When your QB64 program terminates, all sounds are automatically freed - - -''Examples:'' -{{CodeStart}} '' '' -{{Cl|_SNDCLOSE}} h& '' '' -{{CodeEnd}} +* If the sound is still playing, it will be freed automatically after it finishes. +** Closing a looping/paused/etc. sound means it is never freed until the QB64 program terminates. +* When your QB64 program terminates, all sounds are automatically freed. {{PageSeeAlso}} -*{{KW|_SNDSTOP}}, {{KW|_SNDPAUSE}} +*[[_SNDSTOP]], [[_SNDPAUSE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SNDCOPY.txt b/internal/help/_SNDCOPY.txt index b7bf3e19a..ec3e8ef25 100644 --- a/internal/help/_SNDCOPY.txt +++ b/internal/help/_SNDCOPY.txt @@ -3,33 +3,14 @@ The [[_SNDCOPY]] function copies a sound to a new handle so that two or more of {{PageSyntax}} -::: copy_handle& = '''_SNDCOPY('''{{Parameter|handle&}}''')''' +: {{Parameter|copyHandle&}} = [[_SNDCOPY]]({{Parameter|handle&}}) {{PageDescription}} -* Opened sound files must have the "SYNC" capability to use this function. (Currently WAV, OGG, AIF, RIF and VOC) -* Returns a new handle to the same sound data referred to by the source handle. +* Returns a new handle to the a copy in memory of the sound data referred to by the source handle. * No changes to the source handle (such as a volume change) are inherited. * The sound data referred to by the handle and its copies are not freed until all of them are closed. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} - - -''Example:'' -{{CodeStart}} '' '' -h2& = {{Cl|_SNDCOPY}}(h&) '' '' -{{CodeEnd}} +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"SYNC" capability]] to use this function. {{PageSeeAlso}} diff --git a/internal/help/_SNDGETPOS.txt b/internal/help/_SNDGETPOS.txt index a73ae652f..8761f0caa 100644 --- a/internal/help/_SNDGETPOS.txt +++ b/internal/help/_SNDGETPOS.txt @@ -3,32 +3,21 @@ The [[_SNDGETPOS]] function returns the current playing position in seconds usin {{PageSyntax}} -:{{Parameter|position}} = '''_SNDGETPOS('''{{Parameter|handle&}}''')''' +:{{Parameter|position}} = [[_SNDGETPOS]]({{Parameter|handle&}}) {{PageDescription}} -*Returns the currently playing position in seconds from '''MP3''' sound files with the SETPOS capability. +*Returns the current playing position in seconds from an open sound file. *If a sound isn't playing, it returns 0. *If a sound is paused, it returns the paused position. *For a looping sound, the value returned continues to increment and does not reset to 0 when the sound loops. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"SETPOS" capability]] to use this function. -''Example:''To check MP3 files for the SETPOS capability, use [[_SNDPLAY]] with [[_SNDGETPOS]] printed in a loop: +{{PageExamples}} +''Example:'' To check the current playing position in an MP3 file, use [[_SNDPLAY]] with [[_SNDGETPOS]] printed in a loop: {{CodeStart}} '' '' -SoundFile& = {{Cl|_SNDOPEN}}("YourSoundFile.mp3", "VOL,SETPOS,PAUSE") '<<< your MP3 sound file here! +SoundFile& = {{Cl|_SNDOPEN}}("YourSoundFile.mp3") '<<< your MP3 sound file here! {{Cl|_SNDSETPOS}} SoundFile&, 5.5 'set to play sound 5 1/2 seconds into music {{Cl|_SNDPLAY}} SoundFile& 'play sound Do: {{Cl|_LIMIT}} 60 diff --git a/internal/help/_SNDLEN.txt b/internal/help/_SNDLEN.txt index 64d28bf8f..76594c9e5 100644 --- a/internal/help/_SNDLEN.txt +++ b/internal/help/_SNDLEN.txt @@ -1,34 +1,14 @@ {{DISPLAYTITLE:_SNDLEN}} -The [[_SNDLEN]] Function returns the length of a sound in seconds using a handle from the [[_SNDOPEN]] Function. - +The [[_SNDLEN]] function returns the length in seconds of a loaded sound using a handle from the [[_SNDOPEN]] function. {{PageSyntax}} -::: soundlength = '''_SNDLEN ('''{{Parameter|handle&}}''')''' +: {{Parameter|soundLength}} = [[_SNDLEN]]({{Parameter|handle&}}) {{PageDescription}} -*Returns the length of a sound in seconds. -*The opened file must include the "LEN" capability to use this function. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} - - -''Example:'' -{{CodeStart}} '' '' -{{Cl|PRINT}} {{Cl|_SNDLEN}}(h&) '' '' -{{CodeEnd}} +* Returns the length of a sound in seconds. +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"LEN" capability]] to use this function. {{PageSeeAlso}} diff --git a/internal/help/_SNDLIMIT.txt b/internal/help/_SNDLIMIT.txt index 8e8e37ba2..559cbc4a1 100644 --- a/internal/help/_SNDLIMIT.txt +++ b/internal/help/_SNDLIMIT.txt @@ -3,18 +3,18 @@ The [[_SNDLIMIT]] statement stops playing a sound after it has been playing for {{PageSyntax}} -::: '''_SNDLIMIT''' {{Parameter|handle&}}, {{Parameter|numberofseconds!}} +: [[_SNDLIMIT]] {{Parameter|handle&}}, {{Parameter|numberOfSeconds!}} {{Parameters}} -* The ''handle&'' variable name is created using the [[_SNDOPEN]] function from a loaded sound file. -* The ''numberofseconds'' is a [[SINGLE]] value of seconds that the sound will play. +* The {{Parameter|handle&}} variable name is created using the [[_SNDOPEN]] function from a loaded sound file. +* {{Parameter|numberOfSeconds!}} is a [[SINGLE]] value of seconds that the sound will play. {{PageDescription}} -*Sets how long a sound will be played in seconds. -*Set the limit to 0 seconds to remove the limit. -*Cannot be set for playing a looping sound. +*Sets how long a sound will be played in seconds. If the limit is set after the sound is started, the timer starts counting down from when the limit is applied, not from the start of playing. +*Set {{Parameter|numberOfSeconds!}} to 0 seconds to remove the limit. +*Pausing or stopping the sound will also remove the limit. {{PageExamples}} diff --git a/internal/help/_SNDLOOP.txt b/internal/help/_SNDLOOP.txt index 98e70b6d4..e38b13e30 100644 --- a/internal/help/_SNDLOOP.txt +++ b/internal/help/_SNDLOOP.txt @@ -3,17 +3,17 @@ The [[_SNDLOOP]] statement is like [[_SNDPLAY]] but the sound is looped. Uses a {{PageSyntax}} -::: '''_SNDLOOP''' {{Parameter|handle&}} +: [[_SNDLOOP]] {{Parameter|handle&}} {{PageDescription}} -*Plays the sound, looping it. -* [[_SNDSETPOS]] cannot be called while a looping sound is being played. +*Plays the sound identified by {{Parameter|handle&}} in a loop. +{{PageExamples}} ''Example:'' Loading a sound or music file and playing it in a loop until a key is pressed. {{CodeStart}} '' '' -bg = {{Cl|_SNDOPEN}}("back.mid") '<<<<<<<<<< change to your sound file name +bg = {{Cl|_SNDOPEN}}("back.ogg") '<<<<<<<<<< change to your sound file name {{Cl|_SNDLOOP}} bg DO diff --git a/internal/help/_SNDOPEN.txt b/internal/help/_SNDOPEN.txt index 40ffb7812..30b9db171 100644 --- a/internal/help/_SNDOPEN.txt +++ b/internal/help/_SNDOPEN.txt @@ -1,25 +1,28 @@ {{DISPLAYTITLE:_SNDOPEN}} -The '''_SNDOPEN''' function loads a sound file into memory and returns a [[LONG]] handle value above 0. +The [[_SNDOPEN]] function loads a sound file into memory and returns a [[LONG]] handle value above 0. {{PageSyntax}} -::: sound_handle& = '''_SNDOPEN ('''''filename$''[, "[VOL][,][SYNC][,][LEN][,][PAUSE][,][SETPOS]"]''')''' +: {{Parameter|soundHandle&}} = [[_SNDOPEN]]({{Parameter|fileName$}}) + +===Syntax prior to build 20170811/60=== +: {{Parameter|soundHandle&}} = [[_SNDOPEN]]({{Parameter|fileName$}}[, "[VOL][,][SYNC][,][LEN][,][PAUSE][,][SETPOS]"]) {{PageDescription}} -* Returns a [[LONG]] ''sound handle'' value to the sound file in memory. '''A zero value means the sound could NOT be loaded.''' -* The literal or variable [[STRING]] sound ''file name'' can be WAV, OGG, AIFF, RIFF, VOC, MP3, MOD or MIDI file types. -*Capabilities of VOL, LEN, SYNC, SETPOS and PAUSE is a string of parameters separated by commas. It is NOT case sensitive. -* '''ALWAYS check the handle value returned is greater than zero before attempting to play the sound!''' -* The handle can be used by most of the SND sound playing Functions and Subs in QB64 except [[_SNDPLAYFILE]] which plays a sound file name directly and does not use a handle value. +* Returns a [[LONG]] {{Parameter|soundHandle&}} value to the sound file in memory. '''A zero value means the sound could not be loaded.''' +* The literal or variable [[STRING]] sound {{Parameter|fileName$}} can be '''WAV, OGG or MP3''' file types. +** Older versions of QB64 may support ''AIFF, RIFF, VOC, MOD and MIDI''. +* '''Always check the handle value returned is greater than zero before attempting to play the sound.''' +* The handle can be used by most of the _SND sound playing functions and statements in QB64 except [[_SNDPLAYFILE]] which plays a sound file directly from the disk and does not use a handle value. * Handles can be closed with [[_SNDCLOSE]] when the sound is no longer necessary. -*An '''ILLEGAL FUNCTION CALL''' error message means the capabilities$ string was invalid or two NON-SYNC sounds are using the same channel! -* If a WAV sound file won't play, try it using the Windows [[Windows_Libraries#Play_WAV_Sounds|Play WAV sounds library]] to check it or convert the sound file to OGG! +* If a WAV sound file won't play, try it using the Windows [[Windows_Libraries#Play_WAV_Sounds|Play WAV sounds library]] to check it or convert the sound file to OGG. -<center>'''Sound File Capabilities'''</center> +===Older versions=== +* The second parameter ("capabilities") is a string of parameters separated by commas, according to the table below. It is not case sensitive. * Each capability can only be specified once and must be valid for that file or it won't play. Capabilities can be listed in any order. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): +{{TextStart}} '''QB64 versions prior to 1.000''' support the following sound file formats ('''Bold is a guaranteed capability'''): WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] @@ -36,7 +39,7 @@ The '''_SNDOPEN''' function loads a sound file into memory and returns a [[LONG] * The required sound file capabilities can make a difference as to whether a sound file can be played or not and how it can be used. :'''Only one sound can exist on the primary channel, and it must be closed before playing another non-SYNC sound. -<center>See {{KW|_SNDCOPY}} and {{KW|_SNDPLAYCOPY}}</center> +<center>See [[_SNDCOPY]] and [[_SNDPLAYCOPY]]</center> {{TextStart}} '''Capability Descriptions''' "'''VOL'''" can change the volume or balance of the sound using {{Cb|_SNDVOL}} and {{Cb|_SNDBAL}}. @@ -48,17 +51,20 @@ The '''_SNDOPEN''' function loads a sound file into memory and returns a [[LONG] '''When SYNC is not specified, the sound is loaded onto the primary channel.''' {{TextEnd}} +*An '''Illegal Function Call''' error message means the capabilities$ string was invalid or two non-'''SYNC''' sounds are using the same channel. -''Snippet 1:'' Loading a sound file to use in the program later. Only load it ONCE and use the handle any time you want! + +{{PageExamples}} +''Snippet 1:'' Loading a sound file to use in the program later. Only load it once and use the handle any time you want. {{CodeStart}} -h& = {{Cl|_SNDOPEN}}("dog.wav","sync,vol") 'only use the capabilities of that file type +h& = {{Cl|_SNDOPEN}}("dog.wav") IF h& = 0 THEN BEEP ELSE {{Cl|_SNDPLAY}} h& 'check for valid handle before using! {{CodeEnd}} -''Snippet 2:'' Playing a sound from 2 different speakers based on program results. Must use SYNC! +''Snippet 2:'' Playing a sound from 2 different speakers based on program results. {{CodeStart}} '' '' -Laff& = {{Cl|_SNDOPEN}}("KONGlaff.ogg", "SYNC,VOL") 'load sound file and get LONG handle value +Laff& = {{Cl|_SNDOPEN}}("KONGlaff.ogg") 'load sound file and get LONG handle value {{Cl|IF}} LaffX! < -1 {{Cl|THEN}} LaffX! = -1 'set full volume to left speaker {{Cl|IF}} LaffX! > 1 {{Cl|THEN}} LaffX! = 1 'set full volume to right speaker @@ -67,6 +73,67 @@ Laff& = {{Cl|_SNDOPEN}}("KONGlaff.ogg", "SYNC,VOL") 'loa {{CodeEnd}} +''Example:'' Playing a file and controlling playback: +{{CodeStart}} +s& = {{Cl|_SNDOPEN}}("song.ogg") +{{Cl|PRINT}} "{{Cl|READ}}Y"; s& +{{Cl|_SNDPLAY}} s& +{{Cl|_SNDLOOP}} s& + + +xleft = -1 +xright = 1 +DO + k$ = {{Cl|INKEY$}} + {{Cl|SELECT CASE}} k$ + {{Cl|CASE}} "f" + xleft = xleft - 0.1 + {{Cl|_SNDBAL}} s&, xleft, , , 1 + {{Cl|CASE}} "g" + xleft = xleft + 0.1 + {{Cl|_SNDBAL}} s&, xleft, , , 1 + {{Cl|CASE}} "h" + xright = xright - 0.1 + {{Cl|_SNDBAL}} s&, xright, , , 2 + {{Cl|CASE}} "j" + xright = xright + 0.1 + {{Cl|_SNDBAL}} s&, xright, , , 2 + {{Cl|CASE}} "n" + volume = volume - 0.1 + {{Cl|_SNDVOL}} s&, volume + {{Cl|CASE}} "m" + volume = volume + 0.1 + {{Cl|_SNDVOL}} s&, volume + {{Cl|CASE}} "p" + {{Cl|_SNDPAUSE}} s& + {{Cl|CASE}} " " + {{Cl|_SNDPLAY}} s& + {{Cl|CASE}} "i" + {{Cl|PRINT}} {{Cl|_SNDPLAYING}}(s&) + {{Cl|PRINT}} {{Cl|_SNDPAUSED}}(s&) + {{Cl|SLEEP}} + {{Cl|CASE}} "b" + {{Cl|_SNDSETPOS}} s&, 110 + {{Cl|CASE}} "l" + {{Cl|_SNDLIMIT}} s&, 10 + {{Cl|PRINT}} "LIM" + {{Cl|SLEEP}} + {{Cl|CASE}} "k" + {{Cl|_SNDSTOP}} s& + {{Cl|CASE}} "c" + {{Cl|_SNDCLOSE}} s& + {{Cl|SLEEP}} + s2& = {{Cl|_SNDOPEN}}("song.ogg") + {{Cl|CASE}} "d" + s2& = {{Cl|_SNDCOPY}}(s&) + {{Cl|_SNDPLAY}} s2& + {{Cl|END SELECT}} + {{Cl|LOCATE}} 1, 1 + {{Cl|PRINT}} xleft, xright, volume, {{Cl|_SNDGETPOS}}(s&); " " +LOOP +{{CodeEnd}}{{small|Code by Johny B}} + + {{PageSeeAlso}} * [[_SNDCLOSE]], [[_SNDPLAY]], [[_SNDSTOP]] @@ -76,7 +143,7 @@ Laff& = {{Cl|_SNDOPEN}}("KONGlaff.ogg", "SYNC,VOL") 'loa * [[_SNDCOPY]], [[_SNDPLAYCOPY]] * [[_SNDBAL]], [[_SNDLEN]], [[_SNDVOL]] * [[_SNDPLAYFILE]] {{text|(plays a named sound file directly and closes)}} -* [[_SNDRAW]], [[_SNDRATE]], [[_SNDRAWLEN]] {{text|{raw sounds without files)}} +* [[_SNDRAW]], [[_SNDRATE]], [[_SNDRAWLEN]] {{text|(raw sounds without files)}} {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SNDOPENRAW.txt b/internal/help/_SNDOPENRAW.txt index 92ec0b334..d738614be 100644 --- a/internal/help/_SNDOPENRAW.txt +++ b/internal/help/_SNDOPENRAW.txt @@ -1,15 +1,17 @@ {{DISPLAYTITLE:_SNDOPENRAW}} -'''_SNDOPENRAW''' function opens a new channel to shove _SNDRAW content into to manage multiple dynamically generated sounds. +The [[_SNDOPENRAW]] function opens a new channel to fill with _SNDRAW content to manage multiple dynamically generated sounds. {{PageSyntax}} -::::: pipehandle = '''_SNDOPENRAW''' +: {{Parameter|pipeHandle&}} = [[_SNDOPENRAW]] +{{PageDescription}} * You can manage multiple dynamically generated sounds at once without having to worry about mixing. * Use [[_SNDCLOSE]] to remove the pipe sound handles from memory. +{{PageExamples}} ''Example:'' Combining 2 sounds without worrying about mixing: {{CodeStart}} '' '' a = {{Cl|_SNDOPENRAW}} @@ -26,7 +28,7 @@ b = {{Cl|_SNDOPENRAW}} {{PageSeeAlso}} -* [[_SNDRAWDONE]] {{text|(GL only)}} +* [[_SNDRAWDONE]] * [[_SNDRAW]] * [[_SNDCLOSE]] diff --git a/internal/help/_SNDPAUSE.txt b/internal/help/_SNDPAUSE.txt index b9d7bdadf..32286ef9b 100644 --- a/internal/help/_SNDPAUSE.txt +++ b/internal/help/_SNDPAUSE.txt @@ -3,34 +3,12 @@ The [[_SNDPAUSE]] statement pauses a sound using a handle from the [[_SNDOPEN]] {{PageSyntax}} -::: [[_SNDPAUSE]] {{Parameter|handle&}} +: [[_SNDPAUSE]] {{Parameter|handle&}} {{PageDescription}} -* Sound must be playing or statement will not do anything! -* Continue playing by calling [[_SNDPLAY]] -* Sound files opened must have the "PAUSE" capability to use this statement and '''still may not pause'''. -* '''Calling _SNDPAUSE again will not continue playing!''' - -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} - - -''Example:'' -{{CodeStart}} '' '' -{{Cl|_SNDPAUSE}} h& '' '' -{{CodeEnd}} +* Continue playing by calling [[_SNDPLAY]] {{Parameter|handle&}} +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"PAUSE" capability]] to use this function. {{PageSeeAlso}} diff --git a/internal/help/_SNDPAUSED.txt b/internal/help/_SNDPAUSED.txt index 247f01fca..8d6d34ab6 100644 --- a/internal/help/_SNDPAUSED.txt +++ b/internal/help/_SNDPAUSED.txt @@ -3,28 +3,14 @@ The [[_SNDPAUSED]] function checks if a sound is paused. Uses a handle parameter {{PageSyntax}} -::: paused% = '''_SNDPAUSED('''{{Parameter|handle&}}''')''' +: {{Parameter|isPaused%%}} = [[_SNDPAUSED]]({{Parameter|handle&}}) {{PageDescription}} -*Returns -1 if the sound is paused. 0 if not paused. -*Sound files opened must have the "PAUSE" capability to use this function. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +*Returns true (-1) if the sound is paused. False (0) if not paused. -''Example:'' +{{PageExamples}} {{CodeStart}} '' '' {{Cl|PRINT}} {{Cl|_SNDPAUSED}}(h&) '' '' {{CodeEnd}} diff --git a/internal/help/_SNDPLAY.txt b/internal/help/_SNDPLAY.txt index 1ccf111ed..388d41e9d 100644 --- a/internal/help/_SNDPLAY.txt +++ b/internal/help/_SNDPLAY.txt @@ -3,13 +3,14 @@ The [[_SNDPLAY]] statement plays a sound designated by a file handle created by {{PageSyntax}} -::: [[_SNDPLAY]] {{Parameter|handle&}} +: [[_SNDPLAY]] {{Parameter|handle&}} {{PageDescription}} -* Make sure that the handle value is not 0 before attempting to play it. +* Make sure that the {{Parameter|handle&}} value is not 0 before attempting to play it. +{{PageExamples}} ''Example:'' Checking a handle value before playing {{CodeStart}} '' '' {{Cl|IF...THEN|IF}} h& {{Cl|THEN}} {{Cl|_SNDPLAY}} h& '' '' diff --git a/internal/help/_SNDPLAYCOPY.txt b/internal/help/_SNDPLAYCOPY.txt index 2b72e891d..fb5280915 100644 --- a/internal/help/_SNDPLAYCOPY.txt +++ b/internal/help/_SNDPLAYCOPY.txt @@ -1,40 +1,27 @@ {{DISPLAYTITLE:_SNDPLAYCOPY}} -The [[_SNDPLAYCOPY]] statement copies a sound, plays it and automatically closes the copy using a handle parameter passed from [[_SNDOPEN]] or [[_SNDCOPY]] +The [[_SNDPLAYCOPY]] statement copies a sound, plays it, and automatically closes the copy using a handle parameter passed from [[_SNDOPEN]] or [[_SNDCOPY]] {{PageSyntax}} -::: [[_SNDPLAYCOPY]] {{Parameter|handle&}}[, {{Parameter|volume!}}] +: [[_SNDPLAYCOPY]] {{Parameter|handle&}}[, {{Parameter|volume!}}] {{Parameters}} -* The [[LONG]] ''handle&'' value is returned by [[_SNDOPEN]] using a specific sound file. -* The ''volume'' parameter can be any [[SINGLE]] value from 0 (no volume) to 1 (full volume). +* The [[LONG]] {{Parameter|handle&}} value is returned by [[_SNDOPEN]] using a specific sound file. +* The {{Parameter|volume!}} parameter can be any [[SINGLE]] value from 0 (no volume) to 1 (full volume). {{PageDescription}} -* Opened sound files must have the "SYNC" capability to use this statement. (Currently WAV, OGG, AIF, RIF and VOC) *Makes coding easier by doing all of the following automatically: -:#Copies/duplicates the source handle (see [[_SNDCOPY}]] -:#Changes the volume of the copy if volume is passed (file must have "VOL" capability) -:#Plays the copy -:#Closes the copy -* This statement is a better choice than [[_SNDPLAYFILE]] if the sound will be played often, reducing the burden on computer. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +:#Copies/duplicates the source handle (see [[_SNDCOPY]]). +:#Changes the volume of the copy if volume is passed. +:#Plays the copy. +:#Closes the copy. +* This statement is a better choice than [[_SNDPLAYFILE]] if the sound will be played often, reducing the burden on the computer. -''Example 1:'' Playing a sound at half volume. +{{PageExamples}} +''Example 1:'' Playing a previously opened sound at half volume. {{CodeStart}} '' '' {{Cl|_SNDPLAYCOPY}} applause&, 0.5 '' '' {{CodeEnd}} @@ -42,7 +29,7 @@ The [[_SNDPLAYCOPY]] statement copies a sound, plays it and automatically closes ''Example 2:'' Playing a song at random volumes. {{CodeStart}} '' '' -chomp& = _SNDOPEN("chomp.wav", "VOL,SYNC") +chomp& = _SNDOPEN("chomp.wav") _SNDPLAYCOPY chomp&, 0.5 + RND * 0.49 '' '' {{CodeEnd}} @@ -51,7 +38,7 @@ _SNDPLAYCOPY chomp&, 0.5 + RND * 0.49 '' '' {{PageSeeAlso}} * [[_SNDOPEN]] * [[_SNDCOPY]] -* [[_SNDPLAYFILE]] {{text|(plays sound files by file name)}} +* [[_SNDPLAYFILE]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SNDPLAYFILE.txt b/internal/help/_SNDPLAYFILE.txt index 8af71e1ba..037ef1a2f 100644 --- a/internal/help/_SNDPLAYFILE.txt +++ b/internal/help/_SNDPLAYFILE.txt @@ -1,27 +1,25 @@ {{DISPLAYTITLE:_SNDPLAYFILE}} -The [[_SNDPLAYFILE]] statement is a simple command to play a sound file with limited options. +The [[_SNDPLAYFILE]] statement is used to play a sound file without generating a handle, automatically closing it after playback finishes. {{PageSyntax}} -:'''_SNDPLAYFILE''' {{Parameter|filename$}}[, {{Parameter|sync%}}][, {{Parameter|volume!}}] +:[[_SNDPLAYFILE]] {{Parameter|filename$}}[, {{Parameter|ignored%}}][, {{Parameter|volume!}}] {{PageDescription}} -*Filename$ support for: WAVE, OGG, AIFF, RIFF, VOC, MP3, MIDI, MOD -*If sync% is used an opened file must have the "SYNC" capability to play on a side channel. A volume value MUST also be used! -*If sync% is 0 or not used, the sound will be played on the main channel, so playing multiple copies of this sound at the same time won't be possible. (see the [[_SNDOPEN]] function for more information about the way QB64 manages channels) -*If volume! is used an opened file must have the "VOL" capability. -*Volume! is a [[SINGLE]] value from 0(silence) to 1(full volume). If not used, the sound will be played at full volume. +* Supported file formats are '''WAV, OGG and MP3'''. See [[_SNDOPEN]]. +* {{Parameter|ignored%}} is an optional parameter , accepted for historical reasons. +** In versions prior to '''build 20170811/60''', {{Parameter|ignored%}} identified if a sound was to be loaded with [[_SNDOPEN|"SYNC" capabilities]], (-1 for true, 0 for false). This is true for all sound files in the latest versions, making this parameter safe to be ignored. +* {{Parameter|volume!}} is a [[SINGLE]] value from 0 (silence) to 1 (full volume). If not used or outside this range, the sound will be played at full volume. * [[_SNDPLAYFILE]] never creates an error. If the sound cannot be played it takes no further action. -*Changing the usage of sync% and volume! can make a difference as to whether a sound can be played. -*The sound is closed automatically after it finishes playing. -* When a sound will be used often, open the file with {{KW|_SNDOPEN}} and use [[_SNDPLAYCOPY]] to play the handle instead to reduce the burden on a computer. -* '''NOTE:''' Most of the QB64 sound statements and functions require a handle created by [[_SNDOPEN]] to be used. +* The sound is closed automatically after it finishes playing. +* When a sound will be used often, open the file with [[_SNDOPEN]] and use [[_SNDPLAYCOPY]] to play the handle instead to reduce the burden on the computer. -''Example:'' Playing a song at half volume. +{{PageExamples}} +''Example:'' Playing a sound file at half volume. {{CodeStart}} '' '' -{{Cl|_SNDPLAYFILE}} "dog.wav", .5 '' '' +{{Cl|_SNDPLAYFILE}} "dog.wav", , .5 '' '' {{CodeEnd}} diff --git a/internal/help/_SNDPLAYING.txt b/internal/help/_SNDPLAYING.txt index fc31e06e5..92c058d71 100644 --- a/internal/help/_SNDPLAYING.txt +++ b/internal/help/_SNDPLAYING.txt @@ -3,12 +3,12 @@ The [[_SNDPLAYING]] function returns whether a sound is being played. Uses a han {{PageSyntax}} -:{{Parameter|playing%}} = {{KW|_SNDPLAYING}} ({{Parameter|handle&}}) +:{{Parameter|isPlaying%}} = [[_SNDPLAYING]]({{Parameter|handle&}}) {{PageDescription}} -*Returns 0 if a sound is not playing or -1 if it is. -*If a sound is paused, {{KW|_SNDPLAYING}} will return 0. +*Returns false (0) if a sound is not playing or true (-1) if it is. +*If a sound is paused, [[_SNDPLAYING]] returns 0. {{PageExamples}} diff --git a/internal/help/_SNDRATE.txt b/internal/help/_SNDRATE.txt index f2f27ec3f..44e240f46 100644 --- a/internal/help/_SNDRATE.txt +++ b/internal/help/_SNDRATE.txt @@ -1,20 +1,21 @@ {{DISPLAYTITLE:_SNDRATE}} -The '''_SNDRATE''' function returns the sample rate frequency per second of the current computer's sound card. +The [[_SNDRATE]] function returns the sample rate frequency per second of the current computer's sound card. {{PageSyntax}} -::''SampleRate'' = '''_SNDRATE''' +: {{Parameter|sampleRate&}} = [[_SNDRATE]] -* The sample rate frequency per second value returned can be any [[INTEGER]] value. Often it is set at 22050 or 44100. -* When used with [[_SNDRAW]] it can determine the time that a raw sound has been made. Example: t = t + 1 / _SNDRATE -* '''The sound card sample rate is determined by the sound card and it CANNOT be changed!''' +{{PageDescription}} +* The sample rate frequency per second value returned can be any [[LONG]] value. Common values are 22050 or 44100. +* '''The sound card sample rate is determined by the sound card and it cannot be changed.''' -''See [[_SNDRAW]] example.'' +{{PageExamples}} +* See the example in [[_SNDRAW]]. -''See also:'' +{{PageSeeAlso}} * [[_SNDRAW]] * [[_SNDRAWLEN]] diff --git a/internal/help/_SNDRAW.txt b/internal/help/_SNDRAW.txt index 3d5b8e140..b1ff5d673 100644 --- a/internal/help/_SNDRAW.txt +++ b/internal/help/_SNDRAW.txt @@ -1,35 +1,35 @@ {{DISPLAYTITLE:_SNDRAW}} -The '''_SNDRAW''' statement plays sound wave sample frequencies created by a program. +The [[_SNDRAW]] statement plays sound wave sample frequencies created by a program. {{PageSyntax}} -::'''_SNDRAW''' ''left_sample''[, ''right_sample''][, ''pipehandle''] +: [[_SNDRAW]] {{Parameter|leftSample}}[, {{Parameter|rightSample}}][, {{Parameter|pipeHandle&}}] {{Parameters}} -* The ''sample'' value(s) can be any [[SINGLE]] or [[DOUBLE]] literal or variable frequency value from -1.0 to 1.0. -* The ''pipehandle'' argument '''only works in QB64 GL''', it must have been opened using [[_SNDOPENRAW]]. +* The {{Parameter|leftSample}} and {{Parameter|rightSample}} value(s) can be any [[SINGLE]] or [[DOUBLE]] literal or variable frequency value from -1.0 to 1.0. +* The {{Parameter|pipeHandle&}} parameter refers to the sound pipe opened using [[_SNDOPENRAW]]. {{PageDescription}} -* The GL ''pipehandle'' argument allows sound to be played through two or more channels at the same time. -* If only one ''sample'' value is used, the sound will come out of both speakers. -* Using _SNDRAW will pause any currently playing music. (You'll have to generate your own .) -* _SNDRAW is designed for continuous play. It will not produce any sound until a significant number of samples have been queued. Do not expect to hear anything if you only queue one or two samples. -* Ensure that [[_SNDRAWLEN]] is comfortably above 0 (until you've actually finished playing sound). If you are getting occasional random clicks, this generally means that [[_SNDRAWLEN]] has dropped to 0 (unless of course the sounds happen to be clicks). -* _SNDRAW is not intended to queue up many minutes worth of sound! It will probably work but will chew up a lot of memory (and if it gets swapped to disk, your sound could be interrupted abruptly). +* Specifying {{Parameter|pipeHandle&}} allows sound to be played through two or more channels at the same time ('''version 1.000 and up'''). +* If only {{Parameter|leftSample}} value is used, the sound will come out of both speakers. +* Using _SNDRAW will pause any currently playing music. +* _SNDRAW is designed for continuous play. It will not produce any sound until a significant number of samples have been queued. No sound is played if only a few samples are queued. +* Ensure that [[_SNDRAWLEN]] is comfortably above 0 (until you've actually finished playing sound). If you are getting occasional unintended random clicks, this generally means that [[_SNDRAWLEN]] has dropped to 0. +* _SNDRAW is not intended to queue up many minutes worth of sound. It will probably work but will chew up a lot of memory (and if it gets swapped to disk, your sound could be interrupted abruptly). * [[_SNDRATE]] determines how many samples are played per second, but timing is done by the sound card, not your program. * '''Do not attempt to use [[_TIMER]] or [[_DELAY]] or [[_LIMIT]] to control the timing of _SNDRAW. You may use them for delays or to limit your program's CPU usage, but how much to queue should only be based on the [[_SNDRAWLEN]].''' - +{{PageExamples}} ''Example 1:'' Sound using a sine wave with _SNDRAW Amplitude * SIN(8 * ATN(1) * Duration * (Frequency / _SNDRATE)) {{CodeStart}} FREQ = 400 'any frequency desired from 36 to 10,000 Pi2 = 8 * {{Cl|ATN}}(1) '2 * pi Amplitude = .3 'amplitude of the signal from -1.0 to 1.0 SampleRate = {{Cl|_SNDRATE}} 'sets the sample rate -FRate = FREQ / SampleRate +FRate = FREQ / SampleRate' {{Cl|FOR...NEXT|FOR}} Duration = 0 {{Cl|TO}} 5 * SampleRate 'play 5 seconds {{Cl|_SNDRAW}} Amplitude * {{Cl|SIN}}(Pi2 * Duration * FRate) 'sine wave '{{Cl|_SNDRAW}} Amplitude * {{Cl|SGN}}({{Cl|SIN}}(Pi2 * Duration * FRate)) 'square wave @@ -62,7 +62,7 @@ DO WHILE {{Cl|_SNDRAWLEN}} > 0 'Finish any left over queued s LOOP {{Cl|END}} '' '' {{CodeEnd}} -{{small|Code by Artelius the creator of _SNDRAW}} +{{small|Code by Artelius (responsible for the implementation of _SNDRAW)}} ''Example 3:'' Routine uses _SNDRAW to display and play 12 notes from octaves 1 through 9. @@ -102,13 +102,12 @@ SndLoop! = 0 {{small|Code by CodeGuy}} -''See the Music Frequency table in [[SOUND]] - -''See also:'' +{{PageSeeAlso}} * [[_SNDRATE]], [[_SNDRAWLEN]] -* [[_SNDOPENRAW]], [[_SNDRAWDONE]] {{text|(GL only)}} -* [[_SNDOPEN]] {{text|(play sound files)}} +* [[_SNDOPENRAW]], [[_SNDRAWDONE]] +* [[_SNDOPEN]] * [[PLAY]], [[BEEP]] +* Music Frequency table in [[SOUND]]. * [[DTMF Phone Demo]] diff --git a/internal/help/_SNDRAWDONE.txt b/internal/help/_SNDRAWDONE.txt index 3da56a450..e99b9b772 100644 --- a/internal/help/_SNDRAWDONE.txt +++ b/internal/help/_SNDRAWDONE.txt @@ -1,20 +1,21 @@ {{DISPLAYTITLE:_SNDRAWDONE}} -_SNDRAWDONE ensures that the final buffer portion is played in short sound effects even if it is incomplete. - +[[_SNDRAWDONE]] ensures that the final buffer portion is played in short sound effects even if it is incomplete. {{PageSyntax}} -::: [[_SNDRAWDONE]] +: [[_SNDRAWDONE]] -''Details:'' -* It's not necessary to call this at all because the size of a buffer section is about 1/10th of a second. -* For long sound effect it will probably make no difference. -* '''QB64 GL''' programs only. Not available in QB64 SDL versions .954 and older. +{{PageDescription}} +* Use to force playing small buffers of [[_SNDRAW]] data. -''See also:'' -* [[_SNDOPENRAW]] {{text|(GL only)}} +==Availability== +* '''Version 1.000 and up''' + + +{{PageSeeAlso}} +* [[_SNDOPENRAW]] * [[_SNDRAW]] * [[_SNDRAWLEN]] * [[_SNDRATE]] diff --git a/internal/help/_SNDRAWLEN.txt b/internal/help/_SNDRAWLEN.txt index 5ef0bdd8b..6265bd28f 100644 --- a/internal/help/_SNDRAWLEN.txt +++ b/internal/help/_SNDRAWLEN.txt @@ -1,22 +1,24 @@ {{DISPLAYTITLE:_SNDRAWLEN}} -The '''_SNDRAWLEN''' function returns the length, in seconds, of a [[_SNDRAW]] sound currently queued. +The [[_SNDRAWLEN]] function returns the length, in seconds, of a [[_SNDRAW]] sound currently queued. {{PageSyntax}} -:: length# = _SNDRAWLEN +: {{Parameter|length#}} = [[_SNDRAWLEN]] -* Use the _SNDRAWLEN to determine the length of a sound queue during creation and when to stop playing the sound. -* Ensure that _SNDRAWLEN is comfortably above 0 (until you've actually finished playing sound). -* If you are getting occasional random clicks, this generally means that _SNDRAWLEN has dropped to 0. -* The [[_SNDRATE]] determines how many samples are played per second. However, the timing is achieved by the sound card and the _SNDRAWLEN, not your program! -* '''Do NOT attempt to use [[_TIMER]] or [[_DELAY]] or [[_LIMIT]] to control the timing of [[_SNDRAW]] sounds! You may use them as usual for delays or to limit your program's CPU usage, but the decision of how much sound to queue should only be based on the _SNDRAWLEN!''' +{{PageDescription}} +* Use [[_SNDRAWLEN]] to determine the length of a sound queue during creation and when to stop playing the sound. +* Ensure that [[_SNDRAWLEN]] is comfortably above 0 (until you've actually finished playing sound). +* If you are getting occasional random clicks, this generally means that [[_SNDRAWLEN]] has dropped to 0. +* The [[_SNDRATE]] determines how many samples are played per second. However, the timing is achieved by the sound card and [[_SNDRAWLEN]], not your program. +* '''Do not attempt to use [[_TIMER]] or [[_DELAY]] or [[_LIMIT]] to control the timing of [[_SNDRAW]] sounds. You may use them as usual for delays or to limit your program's CPU usage, but the decision of how much sound to queue should only be based on the remaining _SNDRAWLEN'''. -''See Example in [[_SNDRAW]]'' +{{PageExamples}} +* See the example in [[_SNDRAW]] -''See also:'' +{{PageSeeAlso}} * [[_SNDRAW]] * [[_SNDRATE]] diff --git a/internal/help/_SNDSETPOS.txt b/internal/help/_SNDSETPOS.txt index cc70e1c3f..6c3140ea4 100644 --- a/internal/help/_SNDSETPOS.txt +++ b/internal/help/_SNDSETPOS.txt @@ -1,34 +1,22 @@ {{DISPLAYTITLE:_SNDSETPOS}} -The [[_SNDSETPOS]] statement changes the current/starting playing position of a sound in seconds. +The [[_SNDSETPOS]] statement changes the current/starting playing position in seconds of a sound. {{PageSyntax}} -::: [[_SNDSETPOS]] {{Parameter|handle&}}''',''' {{Parameter|position!}} +: [[_SNDSETPOS]] {{Parameter|handle&}}, {{Parameter|position!}} {{PageDescription}} -*Changes the current/starting playing position of a sound in seconds(a [[SINGLE]] value). -*If the seconds position is past the length of the sound the sound will stop playing. -*Function cannot be called while a looping ([[_SNDLOOP]]) sound is being played. -*Opened '''MP3''' files must have the "SETPOS" capability to use this statement. Not all do! -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +*Changes the current/starting playing position in seconds (a [[SINGLE]] value) of a sound in memory. +*If {{Parameter|position!}} is past the length of the sound, playback will be interrupted. +*Function cannot be called while a looping sound is being played (see [[_SNDLOOP]]). +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"SETPOS" capability]] to use this statement. -''Example:''To check MP3 files for the SETPOS capability, use [[_SNDPLAY]] with [[_SNDGETPOS]] printed in a loop +{{PageExamples}} +''Example:'' To check the current playing position in an MP3 file, use [[_SNDPLAY]] with [[_SNDGETPOS]] printed in a loop {{CodeStart}} '' '' -SoundFile& = {{Cl|_SNDOPEN}}("YourSoundFile.mp3", "VOL,SETPOS,PAUSE") '<<< your MP3 sound file here! +SoundFile& = {{Cl|_SNDOPEN}}("YourSoundFile.mp3") '<<< your MP3 sound file here! {{Cl|_SNDSETPOS}} SoundFile&, 5.5 'set to play sound 5 1/2 seconds into music {{Cl|_SNDPLAY}} SoundFile& 'play sound Do: {{Cl|_LIMIT}} 60 diff --git a/internal/help/_SNDSTOP.txt b/internal/help/_SNDSTOP.txt index e97c292ec..7661dd6b4 100644 --- a/internal/help/_SNDSTOP.txt +++ b/internal/help/_SNDSTOP.txt @@ -1,15 +1,16 @@ {{DISPLAYTITLE:_SNDSTOP}} -The [[_SNDSTOP]] statement stops a playing or paused sound using a handle from the [[_SNDOPEN]] or [[_SNDCOPY]] Functions. +The [[_SNDSTOP]] statement stops a playing or paused sound using a handle from the [[_SNDOPEN]] or [[_SNDCOPY]] functions. {{PageSyntax}} -::: _SNDSTOP]] {{Parameter|handle&}} +: [[_SNDSTOP]] {{Parameter|handle&}} {{PageDescription}} -* Sounds can be resumed using {{KW|_SNDPLAY}} with the correct handle. +* Sounds can be resumed using [[_SNDPLAY]] with the correct handle. +{{PageExamples}} ''Example:'' {{CodeStart}} '' '' {{Cl|_SNDSTOP}} h& '' '' diff --git a/internal/help/_SNDVOL.txt b/internal/help/_SNDVOL.txt index be40141d1..a1b10b3c5 100644 --- a/internal/help/_SNDVOL.txt +++ b/internal/help/_SNDVOL.txt @@ -1,39 +1,26 @@ {{DISPLAYTITLE:_SNDVOL}} -The [[_SNDVOL]] statement sets the volume of a sound using a handle from the [[_SNDOPEN]] Function. +The [[_SNDVOL]] statement sets the volume of a sound loaded in memory using a handle from the [[_SNDOPEN]] function. {{PageSyntax}} -::: '''_SNDVOL ('''{{Parameter|handle&}}, {{Parameter|volume!}}''')''' +: [[_SNDVOL]] {{Parameter|handle&}}, {{Parameter|volume!}} {{PageDescription}} -*Volume is a value from 0 (silence) to 1 (full volume). -*An opened sound file must have the "VOL" capability to use this function. -{{TextStart}} QB64 supports the following sound file formats ('''Bold is a guaranteed capability'''): - - WAV = "'''VOL,SYNC,LEN''',PAUSE" [http://www.rarewares.org/ogg-oggdropxpd.php Free WAV to OGG GUI converter] - OGG = "VOL,SYNC,LEN,PAUSE" [http://www.rarewares.org/ogg-oggenc.php Free WAV to OGG converter] - AIF = "VOL,SYNC,LEN,PAUSE" - RIF = "VOL,SYNC,LEN,PAUSE" - VOC = "VOL,SYNC,LEN,PAUSE" - MID = "'''VOL'''" - MOD = "VOL,PAUSE" - MP3 = "'''VOL''',PAUSE,SETPOS" [http://www.freemp3wmaconverter.com/index.html Free WMA, MP3 and OGG converter] - - ''Note:'' {{Cb|_SNDBAL}} only affects MP3 volume. Sound will reside in main channel. -{{TextEnd}} +* {{Parameter|volume!}} is a value from 0 (silence) to 1 (full volume). +* In versions '''prior to build 20170811/60''', the sound identified by {{Parameter|handle&}} must have been opened using the [[_SNDOPEN|"VOL" capability]] to use this function. -''Example:'' +{{PageExamples}} {{CodeStart}} '' '' -h& = {{Cl|_SNDOPEN}}("bell.wav", "SYNC,VOL") +h& = {{Cl|_SNDOPEN}}("bell.wav") {{Cl|_SNDVOL}} h&, 0.5 {{Cl|_SNDPLAY}} h& '' '' {{CodeEnd}} {{PageSeeAlso}} -*{{KW|_SNDOPEN}}, {{KW|_SNDBAL}} +*[[_SNDOPEN]], [[_SNDBAL]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_SOURCE.txt b/internal/help/_SOURCE.txt index b8dfd0723..e499d83b2 100644 --- a/internal/help/_SOURCE.txt +++ b/internal/help/_SOURCE.txt @@ -1,15 +1,15 @@ {{DISPLAYTITLE:_SOURCE}} -The [[_SOURCE]] statement establishes the image SOURCE using a handle created by [[_LOADIMAGE]] or [[_NEWIMAGE]]. +The [[_SOURCE]] statement establishes the image SOURCE using a handle created by [[_LOADIMAGE]], [[_NEWIMAGE]] or [[_COPYIMAGE]]. {{PageSyntax}} -::: [[_SOURCE]] {{Parameter|handle&}} +: [[_SOURCE]] {{Parameter|handle&}} {{PageDescription}} -* The handle is a {{KW|LONG}} integer value from the {{KW|_SOURCE (function)|_SOURCE}} function or a handle created by [[_NEWIMAGE]]. +* The handle is a [[LONG]] integer value from the [[_SOURCE (function)|_SOURCE]] function or a handle created by [[_NEWIMAGE]]. * If the handle is designated as 0, it refers to the current [[SCREEN]] image. -* A source image can only supply information to a program. [[POINT]] and [[GET (graphics statement)|GET]] might require a source other than the present one. +* A source image can only supply information to a program. [[POINT]] and [[GET (graphics statement)|GET]] might require a source other than the one currently active. {{PageExamples}} @@ -25,10 +25,11 @@ a = {{Cl|_NEWIMAGE}}(320,200,13) {{OutputStart}} 15 {{OutputEnd}} -: ''Explanation:'' Create a new image with handle 'a', then use {{KW|_DEST}} to define the image to draw on. Draw a pixel then set the source to 'a' and use {{KW|POINT}} to show what color is in that position. White (15) and is the color set with {{KW|PSET}}. Use {{KW|_DEST}} 0 for the screen to display the results. +: ''Explanation:'' Create a new image with handle 'a', then use [[_DEST]] to define the image to draw on. Draw a pixel then set the source to 'a' and use [[POINT]] to show what color is in that position. White (15) and is the color set with [[PSET]]. Use [[_DEST]] 0 for the screen to display the results. -*''See Example:'' +===More examples=== +See the examples in: * [[Bitmaps]] * [[SAVEIMAGE]] * [[SaveIcon32]] diff --git a/internal/help/_SOURCE_(function).txt b/internal/help/_SOURCE_(function).txt index f351e91c7..fac43201f 100644 --- a/internal/help/_SOURCE_(function).txt +++ b/internal/help/_SOURCE_(function).txt @@ -1,17 +1,18 @@ {{DISPLAYTITLE:_SOURCE (function)}} -The '''_SOURCE''' function returns the present image _SOURCE handle value. +The [[_SOURCE (function)|_SOURCE]] function returns the present image source handle value. {{PageSyntax}} -::: present_source&}} = '''_SOURCE''' +: {{Parameter|currentSource&}} = [[_SOURCE (function)|_SOURCE]] {{PageDescription}} -* Returns a handle value that is a [[LONG]] Integer type. -* Save the source handle to a [[LONG]] variable for later restoration using the {{KW|_SOURCE}} statement. +* Returns a handle value that is a [[LONG]] integer type. +* Save the source handle to a [[LONG]] variable for later restoration using the [[_SOURCE]] statement. -*''See Example:'' +{{PageExamples}} +See the examples in: * [[Bitmaps]] * [[SAVEIMAGE]] * [[SaveIcon32]] diff --git a/internal/help/_STARTDIR$.txt b/internal/help/_STARTDIR$.txt index 7bc1f6a11..307b72d3a 100644 --- a/internal/help/_STARTDIR$.txt +++ b/internal/help/_STARTDIR$.txt @@ -1,16 +1,20 @@ {{DISPLAYTITLE:_STARTDIR$}} -The '''_STARTDIR$''' function returns the path a user called a QB64 program from. +The [[_STARTDIR$]] function returns the path a user called a QB64 program from. {{PageSyntax}} -::: callpath$ = '''_STARTDIR$''' +: {{Parameter|callPath$}} = [[_STARTDIR$]] {{PageDescription}} * Returns a [[STRING]] representing the user's program calling path. -* Available in GL version as of March 2015. -''Example:'' New QB64 path functions: +==Availability== +* '''Version 1.000 and up'''. + + +{{PageExamples}} +''Example:'' Showcasing QB64 path functions: {{CodeStart}} '' '' {{Cl|$CONSOLE}}:ONLY {{Cl|_DEST}} {{Cl|_CONSOLE}} diff --git a/internal/help/_STRCMP.txt b/internal/help/_STRCMP.txt index f06b7e1e2..324539b21 100644 --- a/internal/help/_STRCMP.txt +++ b/internal/help/_STRCMP.txt @@ -1,19 +1,18 @@ {{DISPLAYTITLE:_STRCMP}} -The '''_STRCMP''' function compares the relationship between two strings, comparing upper or lower case. +The [[_STRCMP]] function compares the relationship between two strings, comparing upper or lower case. {{PageSyntax}} -::: comparison% = '''_STRCMP('''''string1$, string2$''')''' +: {{Parameter|comparison%}} = [[_STRCMP]]({{Parameter|string1$}}, {{Parameter|string2$}}) {{PageDescription}} -* Function returns -1 when ''string1$'' is less than ''string2$'', 0 when equal or 1 when ''string1$'' is greater than ''string2$'' -* Upper case letters will be valued less than lower case letters in the [[ASCII]] evaluation. -* '''Note: The function does not return values over 1 or under -1 like some versions!''' +* Function returns -1 when {{Parameter|string1$}} is less than {{Parameter|string2$}}, 0 when equal or 1 when {{Parameter|string1$}} is greater than {{Parameter|string2$}}. +* Upper case letters are valued less than lower case letters in the [[ASCII]] evaluation. -''See also:'' +{{PageSeeAlso}} * [[_STRICMP]] * [[STR$]] * [[STRING]] diff --git a/internal/help/_STRICMP.txt b/internal/help/_STRICMP.txt index 009f05840..edaf9cb9d 100644 --- a/internal/help/_STRICMP.txt +++ b/internal/help/_STRICMP.txt @@ -1,18 +1,18 @@ {{DISPLAYTITLE:_STRICMP}} -The '''_STRICMP''' function compares the relationship between two strings, without regard to upper or lower case letters. +The [[_STRICMP]] function compares the relationship between two strings, ignoring upper or lower case letters. {{PageSyntax}} -::: comparison% = '''_STRICMP('''''string1$, string2$''')''' +: {{Parameter|comparison%}} = [[_STRICMP]]({{Parameter|string1$}}, {{Parameter|string2$}}) {{PageDescription}} -* Function returns -1 when ''string1$'' is less than ''string2$'', 0 when equal or 1 when ''string1$'' is greater than ''string2$'' +* Function returns -1 when {{Parameter|string1$}} is less than {{Parameter|string2$}}, 0 when equal or 1 when {{Parameter|string1$}} is greater than {{Parameter|string2$}}. * Alphabet comparisons will be evaluated without regard to the letter case in the 2 strings. -''See also:'' +{{PageSeeAlso}} * [[_STRCMP]] * [[STR$]] * [[STRING]] diff --git a/internal/help/_TITLE.txt b/internal/help/_TITLE.txt index 9356e302b..8a8e8084c 100644 --- a/internal/help/_TITLE.txt +++ b/internal/help/_TITLE.txt @@ -1,22 +1,23 @@ {{DISPLAYTITLE:_TITLE}} -The [[_TITLE]] statement provides the program name in the title bar of the QB64 program window. +The [[_TITLE]] statement provides the program name in the title bar of the program window. {{PageSyntax}} -::: [[_TITLE]] {{Parameter|Text$}} +: [[_TITLE]] {{Parameter|text$}} {{Parameters}} -* The text can be any literal or variable [[STRING]] or [[ASCII]] character value. +* {{Parameter|text$}} can be any literal or variable [[STRING]] or [[ASCII]] character value. {{PageDescription}} * The title can be changed anywhere in a program procedure. -* The title bar will say "Untitled" if a title is not used. -* Change the title of the [[$CONSOLE]] windows created using: [[SHELL]] "title consoletitle" -* '''Note: A [[_DELAY|delay]] may be required before the title may be set or after when used by a Windows API. +* The title bar will say "Untitled" if a title is not set. +* Change the title of the [[$CONSOLE]] windows created using [[_CONSOLETITLE]] +* '''Note: A [[_DELAY|delay]] may be required before the title can be set.''' See [[_SCREENEXISTS]]. +{{PageExamples}} ''Example 1:'' How to create the window title bar. {{CodeStart}} '' '' {{Cl|_TITLE}} "My New Program" '' '' @@ -59,9 +60,12 @@ Result = GetModuleFileNameA(0, FileName$, {{Cl|LEN}}(FileName$)) {{PageSeeAlso}} -* [[_ICON]] {{text|(Icons can be used in GL only!)}} +* [[_TITLE$]] (function) +* [[_ICON]] * [[_DELAY]] * [[ASCII]] +* [[_CONSOLETITLE]] +* [[_SCREENEXISTS]] {{PageNavigation}} \ No newline at end of file diff --git a/internal/help/_UNSIGNED.txt b/internal/help/_UNSIGNED.txt index 3314b8f52..f534f2934 100644 --- a/internal/help/_UNSIGNED.txt +++ b/internal/help/_UNSIGNED.txt @@ -1,27 +1,23 @@ {{DISPLAYTITLE:_UNSIGNED}} -[[_UNSIGNED]] defines a numerical value as being positive using '''QB64''' only. +[[_UNSIGNED]] defines a numerical value as being only positive. -''TYPE'' {{PageSyntax}} -::: [[DIM]] variable [[AS]] [{{KW|UNSIGNED}}] ''datatype'' +{{PageSyntax}} +: [[DIM]] {{Parameter|variable}} [[AS]] [{{KW|_UNSIGNED}}] {{Parameter|datatype}} -::: variable [[AS]] [{{KW|_UNSIGNED}}] ''datatype'' - -''_DEFINE'' {{PageSyntax}} -::: {{KW|_DEFINE}} {{Parameter|LetterRange}} {{KW|AS}} [{{KW|_UNSIGNED}}] {{Parameter|datatype}} +: [[_DEFINE]] {{Parameter|letterRange}} [[AS]] [{{KW|_UNSIGNED}}] {{Parameter|datatype}} {{PageDescription}} -* When {{KW|_UNSIGNED}} values use negative values the result subtracts from the highest value of the number's type keeping it positive. * Datatype can be any of the following: [[INTEGER]], [[LONG]], [[_BIT]], [[_BYTE]], [[_INTEGER64]], [[_OFFSET]] -*'''[[SINGLE]], [[DOUBLE]] and [[_FLOAT]] variable types cannot be _UNSIGNED!''' -* {{KW|_UNSIGNED}} can be used in a {{KW|_DEFINE}} statement to set undefined variable name first letters as all positive only values. -* Can also be used in {{KW|DIM}} statements or Subprocedure parameter definitions following {{KW|AS}}. -* {{KW|_UNSIGNED}} allows larger positive numerical variable value limits than signed ones. -* The Unsigned variable type suffix used is the '''tilde ~''' before the number's own type suffix: variablename~& +*'''[[SINGLE]], [[DOUBLE]] and [[_FLOAT]] variable types cannot be _UNSIGNED.''' +* [[_UNSIGNED]] can be used in a [[_DEFINE]] statement to set undefined variable name first letters as all positive-only values. +* Can also be used in [[DIM]] statements or subprocedure parameter definitions following [[AS]]. +* [[_UNSIGNED]] allows larger positive numerical variable value limits than signed ones. +* The unsigned variable type suffix used is the '''tilde (~)''', right before the number's own type suffix: {{Parameter|variableName~&}} -<center>How negative values affect the {{KW|_UNSIGNED}} value returned by a {{KW|_BYTE}} (8 bits). </center> +<center>How negative values affect the [[_UNSIGNED]] value returned by a [[_BYTE]] (8 bits). </center> {{WhiteStart}} 00000001 - unsigned & signed are both 1     01111111 - unsigned & signed are both 127   @@ -31,7 +27,8 @@ {{WhiteEnd}} -''Example 1:'' When a signed '''QB64''' [[INTEGER]] value exceeds 32767, the value may become a negative value: +{{PageExamples}} +''Example 1:'' In '''QB64''', when a signed [[INTEGER]] value exceeds 32767, the value may become a negative value: {{CodeStart}} '' '' i% = 38000 {{Cl|PRINT}} i% '' '' @@ -40,7 +37,7 @@ i% = 38000 :''Explanation:'' Use an [[_UNSIGNED]] [[INTEGER]] or a ~% variable type suffix for only positive integer values up to 65535. -''Example 2:'' In '''QB64''' [[_UNSIGNED]] [[INTEGER]] values greater than 65535 cycle over again from zero: +''Example 2:'' In '''QB64''', [[_UNSIGNED]] [[INTEGER]] values greater than 65535 cycle over again from zero: {{CodeStart}} '' '' i~% = 70000 {{Cl|PRINT}} i~% '' '' @@ -76,7 +73,7 @@ i~% = 70000 {{OutputEnd}} -''Explanation:'' The maximum value can only be 65535(32767 + 32768) so the FOR loop repeats itself. Remove the [[_UNSIGNED]] parts and run it again. +''Explanation:'' The maximum value can only be 65535 (32767 + 32768) so the FOR loop repeats itself. Remove the [[_UNSIGNED]] parts and run it again. diff --git a/internal/help/_WHEEL.txt b/internal/help/_WHEEL.txt index a2550dc9d..b690190f0 100644 --- a/internal/help/_WHEEL.txt +++ b/internal/help/_WHEEL.txt @@ -1,18 +1,19 @@ {{DISPLAYTITLE:_WHEEL}} -The '''_WHEEL''' function returns the relative position of a specified wheel number on a controller device. +The [[_WHEEL]] function returns the relative position of a specified wheel number on a controller device. {{PageSyntax}} -::: move = _WHEEL(''wheel_number%'') +: {{Parameter|move}} = [[_WHEEL]]({{Parameter|wheelNumber%}}) * Returns -1 when scrolling up and 1 when scrolling down with 0 indicating no movement since last read. * Add consecutive wheel values to determine a cumulative value over time for scrolling or moving objects. -* The ''wheel_number'' must be a number which does not exceed the number of wheels found by the [[_LASTWHEEL]] function. +* {{Parameter|wheelNumber%}} must be a number which does not exceed the number of wheels found by the [[_LASTWHEEL]] function. * When a mouse indicates it has 3 wheels, the first two are for relative movement reads. The third wheel is for scrolling. -* '''The number of [[_DEVICES]] MUST be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTWHEEL]]!''' +* '''The number of [[_DEVICES]] must be read before using [[_DEVICE$]], [[_DEVICEINPUT]] or [[_LASTWHEEL]].''' +{{PageExamples}} ''Example 1:'' Reading multiple controller device buttons, axis and wheels. {{CodeStart}} '' '' {{Cl|FOR...NEXT|FOR}} i = 1 {{Cl|TO}} {{Cl|_DEVICES}} @@ -57,7 +58,8 @@ DO: {{Cl|_LIMIT}} 30 'main loop : ''Explanation:'' Referencing the [[_MOUSEMOVEMENTX]] function hides the mouse and sets the mouse to a relative movement mode which can be read by [[_WHEEL]]. [[_DEVICEINPUT]](2) returns -1 (true) only when the mouse is moved, scrolled or clicked. -''See also:'' +{{PageSeeAlso}} +* [[_MOUSEWHEEL]] * [[_LASTWHEEL]], [[_LASTBUTTON]], [[_LASTAXIS]] * [[_AXIS]], [[_BUTTON]], [[_BUTTONCHANGE]] * [[_DEVICES]], [[_DEVICE$]], [[_DEVICEINPUT]] diff --git a/internal/help/_WIDTH_(function).txt b/internal/help/_WIDTH_(function).txt index 6dde7e6ff..1d48bd8a3 100644 --- a/internal/help/_WIDTH_(function).txt +++ b/internal/help/_WIDTH_(function).txt @@ -1,21 +1,22 @@ {{DISPLAYTITLE:_WIDTH (function)}} -The '''_WIDTH''' function returns the width of an image handle or current write page. +The [[_WIDTH (function)|_WIDTH]] function returns the width of an image handle or of the current write page. {{PageSyntax}} -::: columns& = '''_WIDTH'''[({{Parameter|imageHandle&}})] +: {{Parameter|columns&}} = [[_WIDTH (function)|_WIDTH]][({{Parameter|imageHandle&}})] {{PageDescription}} * If {{Parameter|imageHandle&}} is omitted, it's assumed to be the handle of the current [[SCREEN]] or write page. -* To get the width of the current program [[SCREEN|screen]] window use zero for the handle value: wide& = _WIDTH(0) +* To get the width of the current program [[SCREEN|screen]] window use zero for the handle value or nothing: {{Parameter|columns&}} = [[_WIDTH (function)|_WIDTH]](0) ''or'' {{Parameter|columns&}} = [[_WIDTH (function)|_WIDTH]] * If the image specified by {{Parameter|imageHandle&}} is in text only([[SCREEN]] 0) mode, the number of characters per row is returned. * If the image specified by {{Parameter|imageHandle&}} is in graphics mode, the number of pixels per row is returned. * If {{Parameter|imageHandle&}} is an invalid handle, then an [[ERROR Codes|invalid handle error]] is returned. -* The maximum pixel coordinate of a program [[SCREEN|screen]] is one less than what the function returns. +* The last visible pixel coordinate of a program [[SCREEN|screen]] is '''[[_WIDTH (function)|_WIDTH]] - 1'''. -''Example:'' A SUB program that centers text in any graphic screen mode except text mode [[SCREEN (statement)|SCREEN]] 0 using '''QB64'''. +{{PageExamples}} +''Example:'' A SUB program that centers text in any graphic screen mode except text mode [[SCREEN (statement)|SCREEN]] 0. {{CodeStart}} @@ -32,17 +33,16 @@ The '''_WIDTH''' function returns the width of an image handle or current write {{CodeEnd}} -: ''Explanation:'' [[_NEWIMAGE]] enlarges a screen to 800 pixels wide which is what '''_WIDTH''' function will return. The center is 800 \ 2 or 400. Since the text width is 8 pixels, that is divided by 8 to get 50 as the center text column. Then half of the text length is subtracted to find the starting text print [[LOCATE]] column. +: ''Explanation:'' [[_NEWIMAGE]] enlarges a screen to 800 pixels wide which is what [[_WIDTH (function)|_WIDTH]] function will return. The center is 800 \ 2 or 400. Since the text width is 8 pixels, that is divided by 8 to get 50 as the center text column. Then half of the text length is subtracted to find the starting text print [[LOCATE]] column. -: ''Note:'' The screen handle parameter is required because using no handle could assume other page handles created by functions like [[_NEWIMAGE]] or [[_PUTIMAGE]]! Use the correct handle in the SUB call! When using SCREEN 0, the MaxCol variable is not needed because _WIDTH returns the number of text columns, not pixels. Use the center value and add 1. -<center>Tcol = (center& + 1) - LEN(txt$) \ 2 </center> +: ''Note:'' The screen handle parameter is required because using no handle could assume other page handles created by functions like [[_NEWIMAGE]] or [[_PUTIMAGE]]. Use the correct handle in the SUB call! When using SCREEN 0, the MaxCol variable is not needed because _WIDTH returns the number of text columns, not pixels. Use the center value and add 1. '''Tcol = (center& + 1) - LEN(txt$) \ 2''' {{PageSeeAlso}} * [[_HEIGHT]], [[_LOADIMAGE]], [[_NEWIMAGE]] -* [[WIDTH]] {{text|(QB statement)}} +* [[WIDTH]] * [[Bitmaps]] diff --git a/internal/help/links.bin b/internal/help/links.bin index e800d38ca..1849081be 100644 --- a/internal/help/links.bin +++ b/internal/help/links.bin @@ -10,11 +10,14 @@ _ASINH,_ASINH _ATAN2,_ATAN2 _ATANH,_ATANH _AUTODISPLAY,_AUTODISPLAY +_AUTODISPLAY,_AUTODISPLAY (function) _AXIS,_AXIS _BACKGROUNDCOLOR,_BACKGROUNDCOLOR _BIT,_BIT _BLEND,_BLEND _BLEND,_BLEND (function) +_BLINK,_BLINK +_BLINK,_BLINK (function) _BLUE,_BLUE _BLUE32,_BLUE32 _BUTTON,_BUTTON @@ -27,12 +30,15 @@ _CLEARCOLOR,_CLEARCOLOR _CLIP,_CLIP _CLIPBOARD$,_CLIPBOARD$ _CLIPBOARD$,_CLIPBOARD$ (statement) +_CLIPBOARDIMAGE,_CLIPBOARDIMAGE (function) +_CLIPBOARDIMAGE,_CLIPBOARDIMAGE _COMMANDCOUNT,_COMMANDCOUNT _CONNECTED,_CONNECTED _CONNECTIONADDRESS$,_CONNECTIONADDRESS$ $CONSOLE,$CONSOLE _CONSOLE,_CONSOLE _CONSOLETITLE,_CONSOLETITLE +_CONTINUE,_CONTINUE _CONTROLCHR,_CONTROLCHR _CONTROLCHR,_CONTROLCHR (function) _COPYIMAGE,_COPYIMAGE @@ -59,6 +65,7 @@ _DEST,_DEST (function) _DEVICE$,_DEVICE$ _DEVICEINPUT,_DEVICEINPUT _DEVICES,_DEVICES +_DIR$,_DIR$ _DIREXISTS,_DIREXISTS _DISPLAY,_DISPLAY _DISPLAY,_DISPLAY (function) @@ -69,6 +76,7 @@ $ELSE,$ELSE $ELSEIF,$ELSEIF $END,$END IF _ERRORLINE,_ERRORLINE +$EXEICON,$EXEICON _EXIT,_EXIT (function) _FILEEXISTS,_FILEEXISTS _FLOAT,_FLOAT @@ -90,6 +98,8 @@ _HIDE,_HIDE _HYPOT,_HYPOT $IF,$IF _ICON,_ICON +_INCLERRORFILE$,_INCLERRORFILE$ +_INCLERRORLINE,_INCLERRORLINE _INTEGER64,_INTEGER64 _KEYCLEAR,_KEYCLEAR _KEYHIT,_KEYHIT @@ -136,6 +146,7 @@ _OFFSET,_OFFSET _OPENCLIENT,_OPENCLIENT _OPENCONNECTION,_OPENCONNECTION _OPENHOST,_OPENHOST +OPTION,OPTION _EXPLICIT _OS$,_OS$ _PALETTECOLOR,_PALETTECOLOR _PALETTECOLOR,_PALETTECOLOR (function) @@ -207,10 +218,14 @@ _STRCMP,_STRCMP _STRICMP,_STRICMP _TANH,Mathematical_Operations _TITLE,_TITLE +_TITLE$,_TITLE$ _UNSIGNED,_UNSIGNED +$VERSIONINFO,$VERSIONINFO $VIRTUALKEYBOARD,$VIRTUALKEYBOARD _WHEEL,_WHEEL _WIDTH,_WIDTH (function) +_WINDOWHANDLE,_WINDOWHANDLE +_WINDOWHASFOCUS,_WINDOWHASFOCUS ABS,ABS ABSOLUTE,CALL ABSOLUTE CALL,CALL ABSOLUTE @@ -218,7 +233,6 @@ ACCESS,ACCESS ALIAS,ALIAS AND,AND AND,AND (boolean) -ANY,ANY APPEND,APPEND AS,AS ASC,ASC @@ -274,7 +288,6 @@ DEFLNG,DEFLNG DEFSNG,DEFSNG DEFSTR,DEFSTR DIM,DIM -DIR$,DIR$ LOOP,DO...LOOP DO,DO...LOOP LOOP,DO...LOOP @@ -751,6 +764,7 @@ _glRecti,_glRecti _glRectiv,_glRectiv _glRects,_glRects _glRectsv,_glRectsv +_GLRENDER,_GLRENDER _glRenderMode,_glRenderMode _glRotated,_glRotated _glRotatef,_glRotatef