The '''DECLARE LIBRARY''' declaration allows the use of external library [[SUB]]

and [[FUNCTION]] procedures supported by QB64.

{{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
* '''This QB64 procedure is available in the Dec 3, 2010 WINDOWS version .923 or
later ONLY!'''
* The declaration can be used with C++ sub-procedures, Windows API, the QB64 SDL
Library and '''QB64''' Dynamic Link Libraries.
* The ''Library name'' is only necessary if a Library is NOT already loaded by Q
B64. Do not include the ''.DLL'' or ''.H'' file name extension.
* ''Library filename''s can be listed to combine more than one DLL or Header fil
e name or path into one DECLARE LIBRARY block.
* C procedures can use a header file name. File code must be included with progr
am code. Do not include the ''.h'' extension.
* ''Procedure_name'' is any program procedure name you want to designate by usin
g [[ALIAS]] with the ''Library_procedure'' name.
* ''Library procedure'' is the actual procedure name used inside of the library
or header file.
* ''Parameters'' used by the Library procedure must be passed by value ([[BYVAL]
]) except for [[STRING]] characters.
* When using a procedure from an '''unsupported''' Dynamic Link Library (DLL fil
e) use [[DECLARE DYNAMIC LIBRARY]].
* '''CUSTOMTYPE''' is already implied when using [[DECLARE DYNAMIC LIBRARY]]. Th
is type of library just allows the same flexibility to apply when referencing ST
ATIC libraries that are used to refer to dynamic libraries.
* '''STATIC''' is the same as [[DECLARE LIBRARY]] except that it prioritizes lin
king 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.
* Declarations can be made inside of [[SUB]] or [[FUNCTION]] procedures. Declara
tions 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 pro
cedure will work and cannot quarantee ANY troubleshooting help!'''
''Example 1:'' Using a QB64 SDL library procedure as a program SUB procedure to
move the mouse pointer to a designated position.
{{CodeStart}} '' ''
{{Cl|DECLARE LIBRARY}}
{{Cl|SUB}} SDL_WarpMouse ({{Cl|BYVAL}} column {{Cl|AS}} {{Cl|LONG}}, {{Cl|BYVA
L}} row {{Cl|AS}} {{Cl|LONG}}) 'SDL procedure name
{{Cl|DECLARE LIBRARY|END DECLARE}}
{{Cl|SCREEN (statement)|SCREEN}} {{Cl|_NEWIMAGE}}(640, 480, 256) 'simulate scre
en 12 with 256 colors
{{Cl|RANDOMIZE}} {{Cl|TIMER}}
DO
{{Cl|_DELAY}} 1
x = {{Cl|RND}} * 640: y = {{Cl|RND}} * 480
{{Cl|LINE}} (x, y)-{{Cl|STEP}}(10, 10), {{Cl|RND}} * 100 + 32, BF
MouseMove x + 5, y + 5
{{Cl|LOOP}} {{Cl|UNTIL}} {{Cl|LEN}}({{Cl|INKEY$}}) 'any keypress quits
{{Cl|END}}
{{Cl|SUB}} MouseMove (x {{Cl|AS}} {{Cl|LONG}}, y {{Cl|AS}} {{Cl|LONG}})
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 t
hese procedures are directly available for use.
<center>'''Using ALIAS to create a program SUB or FUNCTION'''</center&g
t;
{{CodeStart}} '' ''
{{Cl|DECLARE LIBRARY}}
{{Cl|SUB}} MouseMove {{Cl|ALIAS}} SDL_WarpMouse ({{Cl|BYVAL}} column&, {{C
l|BYVAL}} row&)
{{Cl|DECLARE LIBRARY|END DECLARE}} '' ''
{{CodeEnd}}
:''Explanation:'' When a Library procedure is used to represent another procedur
e name use [[ALIAS]] instead. Saves creating a SUB!
''Example 2:'' Don't know if a C function is defined by C++ or QB64? Try using e
mpty quotes.
{{CodeStart}} '' ''
{{Cl|DECLARE LIBRARY}} ""
{{Cl|FUNCTION}} addone& ({{Cl|BYVAL}} value&)
{{Cl|END}} DECLARE '' ''
{{CodeEnd}}
:''Explanation:'' The C function 'addone' exists in a library QB64 already links
to, but it hasn't been defined as a C function or a QB64 function. By using &qu
ot;" we are telling QB64 the function exists in a library which is already
linked to and that it must define the C function before calling it, as well as a
llowing QB64 code to call it. Trying the above code without the "" wil
l fail.
: '''Note: What libraries are or aren't automatically used in the linking proces
s is not formally defined, nor is it guaranteed to stay that way in future versi
ons of QB64.'''
''Example 3:'' For this next example, download the file 'add.lib' and place it i
n you QB64 folder: http://www.qb64.net/add.lib
{{CodeStart}} '' ''
{{Cl|DECLARE LIBRARY}} "add"
{{Cl|FUNCTION}} addtwo& ({{Cl|BYVAL}} value&)
{{Cl|END}} DECLARE
PRINT addtwo(1) '' ''
{{CodeEnd}}
:''Explanation:'' Here, we tell QB64 to link to '''add.lib''' (QB64 searches for
'''add.lib''', '''add.a''', and '''add.o''' in that order and uses the first th
at it finds). The function '''addtwo''' exists inside the library file '''add.li
b''' but isn't defined anywhere else. QB64 creates the C definition for the func
tion '''addtwo''' so that it can be called from our QB64 code.
: '''Note: If the C function definition auto-created by QB64 does not exactly ma
tch the definition in the library file, it will not work. As a result of this it
is often better to provide the C function definitions in the form of a C header
file, such as in the following example.'''
''Example 4:'' NTport is a commercial library hosted at http://www.zealsoftstudi
o.com/ntport/, but it does provide an evaluation version (it has a 3 second wait
pop-up window) which we will use here. You don't need to download NTport, just
download the following 3 files and put them in your QB64 folder:
<center>[http://www.qb64.net/ntport/ntport.lib NTport.lib][http://www.qb64.n
ntport.h NTport.h] [http://www.qb64.net/ntport/ntport.dll Ntport.dll]</center
:'''IMPORTANT:''' The DLL is loaded automatically by the static library, we are
not linking directly to the DLL, we are '''static linking''' (NOT directly or dy
namically linking). This is an important concept to understand!
{{CodeStart}}
DECLARE LIBRARY "ntport"
FUNCTION GetLPTPortAddress% (BYVAL PortNo%)
END DECLARE
PRINT "&H" + HEX$(GetLPTPortAddress%(1))
{{CodeEnd}}
:''Explanation:'' DECLARE LIBRARY also searches for C header files with a '''.h'
'' extension. So in this case it is using the header '''ntport.h''' and linking
with '''ntport.lib''' just by specifying "NTPORT". The C function defi
nitions are stored in '''ntport.h''' so even if our QB64 functions don't exactly
match (eg. LONG instead of INTEGER) it will still work.
:If you look inside ''''ntport.h'''' you'll find the following line containing t
he C function definition of the command we used:
{{TextStart}} WORD WINAPI GetLPTPortAddress(WORD PortNo);
{{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-View
er/3000-10743_4-10598377.html PDF XChange Viewer]
<center>[http://www.libsdl.org/archives/sdldoc-ps.zip SDL Library Ebook Do
cumentation 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 B
rowser 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>
''See also:''
* [[DECLARE DYNAMIC LIBRARY]]
* [[SUB]], [[FUNCTION]]
* [[BYVAL]], [[ALIAS]]
* [[C Libraries]], [[SDL Libraries]], [[DLL Libraries]], [[Windows Libraries]]
* [[Port Access Libraries]]
* [[OpenGL Libraries]]
* [[SFML Libraries]]
* [[SQL Client]]
{{PageNavigation}}