The Ring programming language version 1.6 book - Part 80 of 189
0 likes16 views
The document discusses various low-level functions in Ring for interacting with C code and memory management. It describes functions such as callgc() to manually call the garbage collector, varptr() to get a C pointer for a Ring variable, space() to allocate memory, nullpointer() to pass a NULL pointer, object2pointer() to get a C pointer for a Ring object, and pointer2object() to convert a C pointer to a Ring object.
![Ring Documentation, Release 1.6
setclickevent(Method(:OpenAction))
settooltip("Open File")
} ,
new qtoolbutton(win) {
setbtnimage(self,AppFile("image/save.png"))
setclickevent(Method(:SaveAction))
settooltip("Save")
} ,
new qtoolbutton(win) {
setbtnimage(self,AppFile("image/saveas.png"))
setclickevent(Method(:SaveAsAction))
settooltip("Save As")
} ,
new qtoolbutton(win) {
setbtnimage(self,AppFile("image/close.png"))
setclickevent(Method(:ExitAction))
settooltip("Exit")
}
]
tool1 = win.addtoolbar("files") {
for x in aBtns { addwidget(x) addseparator() }
}
From this example, We know that we can use sub folders for images.
67.12 Creating the Qt resource file using Folder2qrc
When we have large RingQt project that contains a lot of images and files, We need to add these files to the resource
file ( *.qrc ) when distributing applications for Mobile devices.
Instead of adding these files one by one, Ring 1.6 comes with a simple tool that save our time, It’s called Folder2qrc.
Example:
folder2qrc formdesigner.ring
We determine the main source file while we are in the application folder, and Folder2qrc will check all of the files in
the current folder and sub folders, Then add them to the resource file after the mainfile.ringo (In our example this will
be formdesigner.ringo)
The output file will be : project.qrc
You can open it and remove the files that you don’t need in the resources!
67.13 Important Information about Ring2EXE
• Using Ring2EXE to prepare distribution will delete all of the files in the old distribution
for example, if you have target/windows folder then used
ring2exe test3.ring -dist -allruntime
The files in target/windows will be deleted before adding the files again
This is important when you prepare a distribution for Mobile devices
67.12. Creating the Qt resource file using Folder2qrc 768](https://image.slidesharecdn.com/791pdfsamfayedringdoc1-180705072305/85/The-Ring-programming-language-version-1-6-book-Part-80-of-189-6-320.jpg)
![Ring Documentation, Release 1.6
68.1 callgc() function
Use this function to force calling the garbage collector during function execution when you use a loop that create temp.
variables that you don’t free using the assignment operation.
It’s very rare to need this function but it’s useful when you create something like event-loop for your game engine and
start creating lists on the fly when you call functions.
Example
While True
# process events
# call functions using temp. lists like myfunc(["temp list"])
# call the garbage collector
callgc()
End
Tip: In Ring the garbage collector works automatically in the end of function execution or when you use the assign-
ment statement.
68.2 varptr() function
Use the varptr() function when you need to pass a pointer to a C/C++ function.
Syntax:
varptr(cVariableName,cPointerType) —> Low Level Object (C Pointer)
example:
r = 10
z = 20
see r + nl
see varptr("r","int")
see varptr("z","int")
Output:
10
00E3C740
int
2
00E3BEC0
int
2
Note: the low level object is a list contains three items (The Pointer, The Type, The Status)
68.3 space() function
Use the space function to allocate a specific number of bytes in Memory.
68.1. callgc() function 771](https://image.slidesharecdn.com/791pdfsamfayedringdoc1-180705072305/85/The-Ring-programming-language-version-1-6-book-Part-80-of-189-9-320.jpg)
The Ring programming language version 1.6 book - Part 80 of 189
- 1. Ring Documentation, Release 1.6 67.5 Building standalone console application Using the “-static” option we can build executable console application So we don’t have to use ring.dll, ring.so or ring.dylib This avoid only the need to Ring dynamic link library If you are using another libraries, You will need to include it with your application. ring2exe test.ring -static 67.6 Distributing RingAllegro Applications We have test2.ring contains the next code # Just a simple program to test Ring2EXE Tool! # Using RingAllegro load "gameengine.ring" # Give Control to the Game Engine func main # Called by the Game Engine oGame = New Game # Create the Game Object { title = "My First Game" } To build the executable file and prepare for distributing the Game We use “-dist” option and “-allruntime” to include all libraries ring2exe test2.ring -dist -allruntime After executing the previous command On Windows we will have : target/windows folder On Linux we will have : target/linux folder On macOS we will have : target/macos folder The previous command will add all of the Ring runtime libraries to our distribution But we may need only RingAllegro, So it’s better to use the next command ring2exe test2.ring -dist -allegro -cruntime This will produce smaller size distribution and will avoid the runtime files that we don’t need! Also we could use the “-gui” option to hide the console window So it’s better to use the next command ring2exe test2.ring -dist -gui -allegro -cruntime 67.5. Building standalone console application 763
- 2. Ring Documentation, Release 1.6 67.7 Distributing RingQt Applications We have test3.ring contains the next code # Just a simple program to test Ring2EXE Tool! # Using RingQt load "guilib.ring" new qApp { new qWidget() { setwindowtitle("Hello, World!") resize(400,400) show() } exec() } To build the executable file and prepare for distributing the GUI application We use “-dist” option and “-allruntime” to include all libraries ring2exe test3.ring -dist -allruntime After executing the previous command On Windows we will have : target/windows folder On Linux we will have : target/linux folder On macOS we will have : target/macos folder The previous command will add all of the Ring runtime libraries to our distribution But we may need only RingQt, So it’s better to use the next command ring2exe test3.ring -dist -qt -cruntime This will produce smaller size distribution and will avoid the runtime files that we don’t need! Also we could use the “-gui” option to hide the console window So it’s better to use the next command ring2exe test3.ring -dist -gui -qt -cruntime 67.8 Distributing Applications for Mobile using RingQt To prepare a Qt project for your RingQt application (test3.ring) use the “-mobileqt” option Example : ring2exe test3.ring -dist -mobileqt After executing the previous command, We will have the Qt project in target/mobile/qtproject folder The main project file will be project.pro which we can open using the Qt Creator IDE. Also we will have the resource file : project.qrc Another important file is our C++ main file : main.cpp 67.7. Distributing RingQt Applications 764
- 3. Ring Documentation, Release 1.6 67.9 Building the Cards Game for Mobile using RingQt For a better example, consider building an Android package for the Cards game that comes with the Ring language in this folder : ring/application/cards The Cards game folder contains three files cards.ring : The Game source code cards.jpg : The image file used by the game project.qrc : Resource file to be used with the Qt project The resource file contains the next content <RCC> <qresource> <file>cards.ringo</file> <file>cards.jpg</file> </qresource> </RCC> We have two files in the resource file The first file is cards.ringo (The Ring Object File) and the second file is cards.jpg (The image file) As a start, Ring2EXE will generate this resource file in target/mobile/qtproject/project.qrc But this file will contains only cards.ringo (That Ring2EXE will generate by calling Ring compiler) We need to update this resource file to add the image file : cards.jpg After this update, we copy the resource file to the main application folder So when we use Ring2EXE again, Our updated resource file will be used! Now to build the cards game for Mobile 1. Run the next command ring2exe cards.ring -dist -mobileqt 2. Open target/mobile/qtproject/project.pro using Qt creator 3. Build and Run using Qt Creator How the Cards game will find the image file ? RingQt comes with a simple function : AppFile() that we can use to determine the files that we may access on Desktop or Mobile platforms The next code from cards.ring mypic = new QPixmap(AppFile("cards.jpg")) So all what you need is using AppFile() function around your image files! 67.10 Building the Weight History Application for Mobile using RingQt Another example to distribute your application for Mobile Devices using Ring2EXE and Qt 67.9. Building the Cards Game for Mobile using RingQt 765
- 4. Ring Documentation, Release 1.6 consider building an Android package for the Weight History application that comes with the Ring language in this folder : ring/application/weighthistory The Weight History application folder contains four files weighthistory.ring : The application source code weighthistory.db : The SQLite database project.qrc : The resource file for the Qt project main.cpp : The main C++ source file for the Qt project To build the Weight History application for Mobile 1. Run the next command ring2exe weighthistory.ring -dist -mobileqt 2. Open target/mobile/qtproject/project.pro using Qt creator 3. Build and Run using Qt Creator The resource file (project.qrc) contains two files <RCC> <qresource> <file>weighthistory.ringo</file> <file>weighthistory.db</file> </qresource> </RCC> The first file is weighthistory.ringo (Ring Object File - Generated by Ring2EXE by calling Ring compiler) The database file : weighthistory.db The main.cpp contains the next little update, To copy the database file from resources to a writable location on the mobile device QString path3 ; path3 = path+"/weighthistory.db"; QFile::copy(":/weighthistory.db",path3); You will need to do this with database files only! When we use Ring2EXE, the tool will check for project.qrc and main.cpp, if they exist then your updated files will be used in target/mobile/qtproject instead of the default version generated by Ring2EXE So Use Ring2EXE to generate these files, Then copy them to your application folder when you update them. 67.11 Building the Form Designer for Mobile using RingQt To build the Form Designer application (ring/applications/formdesigner) for Mobile 1. Run the next command ring2exe formdesigner.ring -dist -mobileqt 2. Open target/mobile/qtproject/project.pro using Qt creator 3. Build and Run using Qt Creator 67.11. Building the Form Designer for Mobile using RingQt 766
- 5. Ring Documentation, Release 1.6 in the folder ring/application/formdesigner You will find the resource file : project.qrc It will be used automatically by Ring2EXE <RCC> <qresource> <file>formdesigner.ringo</file> <file>image/allevents.png</file> <file>image/checkbox.png</file> <file>image/close.png</file> <file>image/combobox.bmp</file> <file>image/datepicker.bmp</file> <file>image/dial.png</file> <file>image/formdesigner.png</file> <file>image/frame.png</file> <file>image/grid.bmp</file> <file>image/hyperlink.png</file> <file>image/image.png</file> <file>image/label.png</file> <file>image/layout.png</file> <file>image/lcdnumber.png</file> <file>image/listview.png</file> <file>image/lock.png</file> <file>image/new.png</file> <file>image/open.png</file> <file>image/progressbar.png</file> <file>image/project.png</file> <file>image/pushbutton.png</file> <file>image/radiobutton.png</file> <file>image/save.png</file> <file>image/saveas.png</file> <file>image/select.png</file> <file>image/slider.png</file> <file>image/spinner.bmp</file> <file>image/statusbar.png</file> <file>image/tab.png</file> <file>image/textarea.png</file> <file>image/textfield.png</file> <file>image/timer.png</file> <file>image/toolbar.png</file> <file>image/tree.bmp</file> <file>image/videowidget.png</file> <file>image/webview.png</file> </qresource> </RCC> As we did in the Cards game, The Form Designer will use the AppFile() function to determine the name of the Image files. The next code from ring/applications/formdesigner/mainwindow/formdesignerview.ring func CreateToolBar aBtns = [ new qtoolbutton(win) { setbtnimage(self,AppFile("image/new.png")) setclickevent(Method(:NewAction)) settooltip("New File") } , new qtoolbutton(win) { setbtnimage(self,AppFile("image/open.png")) 67.11. Building the Form Designer for Mobile using RingQt 767
- 6. Ring Documentation, Release 1.6 setclickevent(Method(:OpenAction)) settooltip("Open File") } , new qtoolbutton(win) { setbtnimage(self,AppFile("image/save.png")) setclickevent(Method(:SaveAction)) settooltip("Save") } , new qtoolbutton(win) { setbtnimage(self,AppFile("image/saveas.png")) setclickevent(Method(:SaveAsAction)) settooltip("Save As") } , new qtoolbutton(win) { setbtnimage(self,AppFile("image/close.png")) setclickevent(Method(:ExitAction)) settooltip("Exit") } ] tool1 = win.addtoolbar("files") { for x in aBtns { addwidget(x) addseparator() } } From this example, We know that we can use sub folders for images. 67.12 Creating the Qt resource file using Folder2qrc When we have large RingQt project that contains a lot of images and files, We need to add these files to the resource file ( *.qrc ) when distributing applications for Mobile devices. Instead of adding these files one by one, Ring 1.6 comes with a simple tool that save our time, It’s called Folder2qrc. Example: folder2qrc formdesigner.ring We determine the main source file while we are in the application folder, and Folder2qrc will check all of the files in the current folder and sub folders, Then add them to the resource file after the mainfile.ringo (In our example this will be formdesigner.ringo) The output file will be : project.qrc You can open it and remove the files that you don’t need in the resources! 67.13 Important Information about Ring2EXE • Using Ring2EXE to prepare distribution will delete all of the files in the old distribution for example, if you have target/windows folder then used ring2exe test3.ring -dist -allruntime The files in target/windows will be deleted before adding the files again This is important when you prepare a distribution for Mobile devices 67.12. Creating the Qt resource file using Folder2qrc 768
- 7. Ring Documentation, Release 1.6 ring2exe test3.ring -dist -mobileqt If you modified the resource file : project.qrc or the main file : main.cpp Don’t forget to copy them to the application folder! So Ring2EXE can use the updated version if you tried the previous command again! • Ring2EXE is written in Ring, and you can read the source code from https://github.com/ring-lang/ring/blob/master/ring2exe/ring2exe.ring • The libraries information are stored in a separated file, So this file can be updated in the future automatically to support new libraries https://github.com/ring-lang/ring/blob/master/ring2exe/ring2exe.data 67.13. Important Information about Ring2EXE 769
- 8. CHAPTER SIXTYEIGHT LOW LEVEL FUNCTIONS In this chapter we will learn about the low level functions provided by Ring • callgc() • varptr() • space() • nullpointer() • object2pointer() • pointer2object() • ptrcmp() • ringvm_cfunctionslist() • ringvm_functionslist() • ringvm_classeslist() • ringvm_packageslist() • ringvm_memorylist() • ringvm_calllist() • ringvm_fileslist() • ringvm_settrace() • ringvm_tracedata() • ringvm_traceevent() • ringvm_tracefunc() • ringvm_scopescount() • ringvm_evalinscope() • ringvm_passerror() • ringvm_hideerrorMsg() • ringvm_callfunc() 770
- 9. Ring Documentation, Release 1.6 68.1 callgc() function Use this function to force calling the garbage collector during function execution when you use a loop that create temp. variables that you don’t free using the assignment operation. It’s very rare to need this function but it’s useful when you create something like event-loop for your game engine and start creating lists on the fly when you call functions. Example While True # process events # call functions using temp. lists like myfunc(["temp list"]) # call the garbage collector callgc() End Tip: In Ring the garbage collector works automatically in the end of function execution or when you use the assign- ment statement. 68.2 varptr() function Use the varptr() function when you need to pass a pointer to a C/C++ function. Syntax: varptr(cVariableName,cPointerType) —> Low Level Object (C Pointer) example: r = 10 z = 20 see r + nl see varptr("r","int") see varptr("z","int") Output: 10 00E3C740 int 2 00E3BEC0 int 2 Note: the low level object is a list contains three items (The Pointer, The Type, The Status) 68.3 space() function Use the space function to allocate a specific number of bytes in Memory. 68.1. callgc() function 771
- 10. Ring Documentation, Release 1.6 Syntax: Space(nBytesCount) ---> String Example: mystring = space(200) See "String Size : " + len(mystring) + nl See "String : " + mystring + nl See "String Pointer : " See varptr("mystring","char *") Output: String Size : 200 String : String Pointer : 00FF8FE8 char * 2 Note: You may need the space() and VarPtr() functions to pass buffers to C functions. 68.4 nullpointer() function You may need to pass the NULL pointer to a C function that may expect a pointer as parameter and accept NULL pointers for optional parameters. Example: The next example uses the SDL_BlitSurface() function from the LibSDL Library through RingSDL The function accept SDL_Rect pointers in the second and the last parameter. Also the function accept NULL pointers, so we can pass them using the NULLPointer() Function. SDL_BlitSurface(text, nullpointer(), surface, nullpointer()) Note: The previous code doesn’t work alone, you need to learn how to use RingSDL first. Tip: We can pass NULL as parameter instead of using NULLPointer() 68.5 object2pointer() function Use this function to get a C pointer for Ring lists and objects Syntax: object2pointer(List|Object) --> Low Level Object ( C Pointer ) 68.6 pointer2object() function Use this function to get the Ring list and/or object from the low level object (C Pointer) 68.4. nullpointer() function 772