Ring Documentation, Release 1.5.

71.13 Filtering using Expressions

using <filter> and </filter> we can include/exclude parts of the configuration file based on a condition, for example
<filter> iswindows()
... functions related to windows
</filter>

71.14 Constants Type

The default type for constant is Number But Some constants may be another type, for example (pointer : void *)
before using <constant> and </constant> we can use <runcode> and </runcode> to determine the constant type using
two global variables used by the code generator.
The first variable is $nDefaultConstantType which can be * C_CONSTANT_TYPE_NUMBER *
C_CONSTANT_TYPE_STRING * C_CONSTANT_TYPE_POINTER
if we are using C_CONSTANT_TYPE_POINTER then we will need the second global variable which is $cDefault-
ConstantPointerType to determine the pointer type.
Example :
The next example uses this feature to define constants in the FreeGLUT library
<runcode>
$nDefaultConstantType = C_CONSTANT_TYPE_POINTER
$cDefaultConstantPointerType = "void"
</runcode>
<constant>
GLUT_STROKE_ROMAN
GLUT_STROKE_MONO_ROMAN
GLUT_BITMAP_9_BY_15
GLUT_BITMAP_8_BY_13
GLUT_BITMAP_TIMES_ROMAN_10
GLUT_BITMAP_TIMES_ROMAN_24
GLUT_BITMAP_HELVETICA_10
GLUT_BITMAP_HELVETICA_12
GLUT_BITMAP_HELVETICA_18
</constant>

71.15 Configuration file for the Allegro Library

The next configuration file enable us to use the Allegro library functions. The configuration file size is less than 1000
lines. when the code generator take this file as input the generated source code file in the C language will be 12000
lines of code!
We can see this configuration file as a complete example about using the code generator Also we can use it to know
the functions that can be used from RingAllegro when you use it to create 2D games!
<code>
#define ALLEGRO_NO_MAGIC_MAIN

#include <allegro5/allegro.h>
#include "allegro5/allegro_image.h"

71.13. Filtering using Expressions 785

 Ring Documentation, Release 1.5.4

#include <allegro5/allegro_font.h>
#include <allegro5/allegro_ttf.h>
#include <allegro5/allegro_audio.h>
#include <allegro5/allegro_acodec.h>
#include <allegro5/allegro_opengl.h>
#include <allegro5/allegro_direct3d.h>
#include <allegro5/allegro_color.h>
#include <allegro5/allegro_memfile.h>
#include "allegro5/allegro_native_dialog.h"
#include <allegro5/allegro_physfs.h>
#include <allegro5/allegro_primitives.h>
</code>

<funcstart>
al
</funcstart>

<struct>
ALLEGRO_EVENT { type , keyboard.keycode , mouse.x , mouse.y }
ALLEGRO_TIMEOUT
ALLEGRO_SAMPLE_ID
ALLEGRO_COLOR
</struct>

<register>
void al_exit(void)
</register>

<code>
RING_FUNC(ring_al_exit)
{
if ( RING_API_PARACOUNT != 0 ) {
RING_API_ERROR(RING_API_BADPARACOUNT);
return ;
}
exit(0);
}
</code>

int al_init(void)

<comment>
configuration files
</comment>

<runcode>
aNumberTypes + "al_fixed"
</runcode>

ALLEGRO_CONFIG *al_create_config(void)
void al_destroy_config(ALLEGRO_CONFIG *config)
ALLEGRO_CONFIG *al_load_config_file(const char *filename)
ALLEGRO_CONFIG *al_load_config_file_f(ALLEGRO_FILE *file)
bool al_save_config_file(const char *filename, const ALLEGRO_CONFIG *config)
bool al_save_config_file_f(ALLEGRO_FILE *file, const ALLEGRO_CONFIG *config)
void al_add_config_section(ALLEGRO_CONFIG *config, const char *name)

Note: we just provided part of the configuration file, for complete copy check the Ring source code distribution.

71.15. Configuration file for the Allegro Library 786

 Ring Documentation, Release 1.5.4

71.16 Threads Support

Next, another part of the configutaiton file, it’s important because we can learn from it how to add threads to our Ring
applications by using a threads library.
The idea is using ring_vm_mutexfunctions() and ring_vm_runcodefromthread() to execute Ring code.
<comment>
Threads
</comment>

<code>
void *al_func_thread(ALLEGRO_THREAD *thread, void *pPointer)
{
List *pList;
VM *pVM;
const char *cStr;
pList = (List *) pPointer ;
pVM = (VM *) ring_list_getpointer(pList,2);
cStr = ring_list_getstring(pList,1);
ring_vm_runcodefromthread(pVM,cStr);
ring_list_delete(pList);
return NULL;
}

RING_FUNC(ring_al_create_thread)
{
ALLEGRO_THREAD *pThread;
List *pList;
if ( RING_API_PARACOUNT != 1 ) {
RING_API_ERROR(RING_API_MISS1PARA);
return ;
}
if ( ! RING_API_ISSTRING(1) ) {
RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
pList = ring_list_new(0);
ring_list_addstring(pList,RING_API_GETSTRING(1));
ring_list_addpointer(pList,pPointer);
ring_vm_mutexfunctions((VM *) pPointer,al_create_mutex,
al_lock_mutex,al_unlock_mutex,al_destroy_mutex);
pThread = al_create_thread(al_func_thread, pList);
al_start_thread(pThread);
RING_API_RETCPOINTER(pThread,"ALLEGRO_THREAD");
}

RING_FUNC(ring_al_run_detached_thread)
{
List *pList;
if ( RING_API_PARACOUNT != 1 ) {
RING_API_ERROR(RING_API_MISS1PARA);
return ;
}
if ( ! RING_API_ISSTRING(1) ) {

71.16. Threads Support 787

 Ring Documentation, Release 1.5.4

RING_API_ERROR(RING_API_BADPARATYPE);
return ;
}
pList = ring_list_new(0);
ring_list_addstring(pList,RING_API_GETSTRING(1));
ring_list_addpointer(pList,pPointer);
ring_vm_mutexfunctions((VM *) pPointer,al_create_mutex,
al_lock_mutex,al_unlock_mutex,al_destroy_mutex);
al_run_detached_thread(al_func_thread, pList);
}
</code>

<register>
ALLEGRO_THREAD *al_create_thread(void)
void al_run_detached_thread(void)
</register>

void al_start_thread(ALLEGRO_THREAD *thread)

void al_join_thread(ALLEGRO_THREAD *thread, void **ret_value)
void al_set_thread_should_stop(ALLEGRO_THREAD *thread)
bool al_get_thread_should_stop(ALLEGRO_THREAD *thread)
void al_destroy_thread(ALLEGRO_THREAD *thread)
ALLEGRO_MUTEX *al_create_mutex(void)
ALLEGRO_MUTEX *al_create_mutex_recursive(void)
void al_lock_mutex(ALLEGRO_MUTEX *mutex)
void al_unlock_mutex(ALLEGRO_MUTEX *mutex)
void al_destroy_mutex(ALLEGRO_MUTEX *mutex)
ALLEGRO_COND *al_create_cond(void)
void al_destroy_cond(ALLEGRO_COND *cond)
void al_wait_cond(ALLEGRO_COND *cond, ALLEGRO_MUTEX *mutex)

71.17 Code Generator Rules for Wrapping C++ Classes

• We can define classes between <class> and </class>

• Between <class> and <class> we set attributes like “name, nonew, para, parent, codename, passvmpointer and
abstract”
• we set the attributes using the style attributename:value or attributename only if no values are required
• The “name” attribute determine the class name in C++ code and this name will be the default name in the Ring
code
• The nonew instruction means that we don’t need new/delete methods
• The parent attribute determine the parent class name
• The codename attribute determine another class name in C++ code
• The passvmpoint instruction means passing the Ring VM pointer to the class constructor when we create new
objects, this happens when we set the codename attribute to a class the we will define and this class need the
Virtual Machine pointer (for example to use it to execute Ring code from C++ code).
• The abstract instruction means that no new method is required for this class “no objects will be created”.
• Using <nodllstartup> we can avoid #include “ring.h”, We need this to write our startup code.
• Using <libinitfunc> we can change the function name that register the library functions
• Using <ignorecpointertype> we can ignore pointer type check

71.17. Code Generator Rules for Wrapping C++ Classes 788

 Ring Documentation, Release 1.5.4

• Using the aStringTypes list when can defined new types that treated like const char *
• Using the aBeforeReturn list when can define code that is inserted after the variable name when we return that
variable from a function
• Using the aNewMethodName list we can define another method name to be used in Ring code when we call
the C++ method. this feature is required because some C++ method may be identical to Ring Keywords like
“load”,”next”,”end” and “done”.
• in method prototype - when we use @ in the method name, we mean that we have the same method with different
parameters (As in C++)

71.18 Using configuration file that wrap C++ Library

To run the code generator to generate code for using C++ library in the Ring application, we can do that as we did
with using C libraries but here we will generate .cpp file instead of *.c file. Also we will determine another file to be
generated (.ring). This file will contains classes in Ring code that wraps C++ functions for using C++ classes and
objects.
ring parsec.ring qt.cf ring_qt.cpp ring_qt.ring

71.19 Configuration file for the Qt Framework

The next configuration file is used to wrap many Qt classes The configuration file is around 3500 lines and generate
C++ code around 56000 lines and generate also Ring code around 9000 lines.
<nodllstartup>

<libinitfunc> ring_qt_start

<ignorecpointertype>

<code>

extern "C" {
#include "ring.h"
}

#include "ring_qt.h"
#include "gpushbutton.h"
#include "gaction.h"
#include "glineedit.h"
#include "gtextedit.h"
#include "glistwidget.h"
#include "gtreeview.h"
#include "gtreewidget.h"
#include "gcombobox.h"
#include "gtabwidget.h"
#include "gtablewidget.h"
#include "gprogressbar.h"
#include "gspinbox.h"
#include "gslider.h"
#include "gdial.h"
#include "gwebview.h"
#include "gcheckbox.h"

71.18. Using configuration file that wrap C++ Library 789

 Ring Documentation, Release 1.5.4

#include "gradiobutton.h"
#include "gbuttongroup.h"
#include "gvideowidget.h"
#include "gtimer.h"
#include "gtcpserver.h"
#include "giodevice.h"
#include "gabstractsocket.h"
#include "gtcpsocket.h"
#include "gcolordialog.h"
#include "gallevents.h"
#include <QApplication>
#include <QObject>
#include <QWidget>
#include <QLabel>
#include <QPixmap>
#include <QIcon>
#include <QSize>
#include <QPushButton>
#include <QMainWindow>
#include <QVBoxLayout>
#include <QHBoxLayout>
#include <QLineEdit>
#include <QTextEdit>
#include <QListWidget>
#include <QTreeView>
#include <QDir>
#include <QFileSystemModel>
#include <QTreeWidget>
#include <QTreeWidgetItem>
#include <QComboBox>
#include <QVariant>
#include <QMenuBar>
#include <QMenu>
#include <QToolBar>
#include <QMainWindow>
#include <QStatusBar>
#include <QDockWidget>
#include <QTabWidget>
#include <QTableWidget>
#include <QTableWidgetItem>
#include <QSizePolicy>
#include <QFrame>
#include <QAbstractScrollArea>
#include <QAbstractItemView>
#include <QProgressBar>
#include <QSpinBox>
#include <QSlider>
#include <QAbstractSlider>
#include <QDateEdit>
#include <QDateTimeEdit>
#include <QAbstractSpinBox>
#include <QDial>
#include <QWebView>
#include <QUrl>
#include <QCheckBox>
#include <QRadioButton>
#include <QButtonGroup>
#include <QMediaPlayer>

71.19. Configuration file for the Qt Framework 790

 Ring Documentation, Release 1.5.4

#include <QMediaPlaylist>
#include <QVideoWidget>
#include <QPrinter>
#include <QAction>
#include <QEvent>
#include <QMessageBox>
#include <QTimer>
#include <QFileDialog>
#include <QPainter>
#include <QPicture>
#include <QPen>
#include <QColor>
#include <QPrinter>
#include <QFont>
#include <QWebSettings>
#include <QBrush>
#include <QByteArray>
#include <QIODevice>
#include <QAbstractSocket>
#include <QTcpSocket>
#include <QTcpServer>
#include <QNetworkProxy>
#include <QHostAddress>
#include <QHostInfo>
#include <QList>
#include <QFileInfo>
#include <QDirModel>
#include <QModelIndex>
#include <QFontDialog>
#include <QDialog>
#include <QTextCursor>
#include <QTextBlock>
#include <QTextDocumentFragment>
#include <QColorDialog>
#include <QHeaderView>
#include <QStringList>
#include <QKeySequence>
#include <QLCDNumber>
#include <QInputDialog>
#include <QDesktopWidget>
#include <QRect>
#include <QTextDocument>

extern "C" {

#define RING_DLL __declspec(dllexport)

RING_DLL void ringlib_init(RingState *pRingState)

{

new QApplication(pRingState->argc,pRingState->argv);
ring_qt_start(pRingState) ;
}

}
</code>

71.19. Configuration file for the Qt Framework 791

 Ring Documentation, Release 1.5.4

<runcode>
aStringTypes + "QString"
aBeforeReturn + ["QString",".toStdString().c_str()"]
aNewMethodName + ["QWebView","load","loadpage"]
aNewMethodName + ["QMediaPlaylist","load","loadfile"]
aNewMethodName + ["QMediaPlaylist","next","movenext"]
aNewMethodName + ["QPainter","end","endpaint"]
aNewMethodName + ["QPicture","load","loadfile"]
aNewMethodName + ["QLineEdit","end","endtext"]
aNewMethodName + ["QDialog","done","donedialog"]
aNewMethodName + ["QTextDocument","end","enddoc"]
aNewMethodName + ["QTextBlock","next","nextblock"]
</runcode>

<class>
name: qApp
nonew
</class>

<register>
void exec(void)
void quit(void)
void processEvents(void)
</register>

<code>

RING_FUNC(ring_qApp_quit)
{
qApp->quit();
}

RING_FUNC(ring_qApp_exec)
{
qApp->exec();
}

RING_FUNC(ring_qApp_processEvents)
{
qApp->processEvents();
}

</code>

<class>
name: QObject
para: void
</class>

bool blockSignals(bool block)

QObjectList children(void)
void dumpObjectInfo(void)
void dumpObjectTree(void)
bool inherits(const char *className)
void installEventFilter(QObject *filterObj)
bool isWidgetType(void)
void killTimer(int id)
void moveToThread(QThread *targetThread)

71.19. Configuration file for the Qt Framework 792

 Ring Documentation, Release 1.5.4

QString objectName(void)
QObject *parent(void)
QVariant property(const char *name)
void removeEventFilter(QObject *obj)
void setObjectName(QString)
void setParent(QObject *parent)
bool setProperty(const char *name, QVariant)
bool signalsBlocked(void)
int startTimer(int interval)
QThread *thread(void)
void deleteLater(void)

<class>
name: QWidget
para: void
parent: QObject
</class>

bool acceptDrops(void)
QString accessibleDescription(void)
QString accessibleName(void)
void activateWindow(void)
void addAction(QAction *action)
void adjustSize(void)
bool autoFillBackground(void)
int backgroundRole(void)
QSize baseSize(void)
QWidget *childAt(int x, int y)
QRect childrenRect(void)
QRegion childrenRegion(void)
void clearFocus(void)
void clearMask(void)
QMargins contentsMargins(void)
QRect contentsRect(void)
int contextMenuPolicy(void)
QCursor cursor(void)
int effectiveWinId(void)
void ensurePolished(void)
int focusPolicy(void)
QWidget *focusProxy(void)
QWidget *focusWidget(void)
QFont font(void)
QFontInfo fontInfo(void)
QFontMetrics fontMetrics(void)
int foregroundRole(void)
QRect frameGeometry(void)
QSize frameSize(void)
QRect geometry(void)
void getContentsMargins(int *left, int *top, int *right, int *bottom)
void grabGesture(int gesture, int flags)
void grabKeyboard(void)
void grabMouse(void)
int grabShortcut(QKeySequence , int context)
QGraphicsEffect *graphicsEffect(void)
QGraphicsProxyWidget *graphicsProxyWidget(void)
bool hasFocus(void)
bool hasMouseTracking(void)
int height(void)

71.19. Configuration file for the Qt Framework 793

 Ring Documentation, Release 1.5.4

int heightForWidth(int w)
int inputMethodHints(void)
QVariant inputMethodQuery(int query)
void insertAction(QAction *before, QAction *action)
bool isActiveWindow(void)
bool isAncestorOf(QWidget *child)
bool isEnabled(void)
bool isEnabledTo(QWidget *ancestor)
bool isFullScreen(void)
bool isHidden(void)
bool isMaximized(void)
bool isMinimized(void)
bool isModal(void)
bool isVisible(void)
bool isVisibleTo(QWidget *ancestor)
bool isWindow(void)
bool isWindowModified(void)
QLayout *layout(void)
int layoutDirection(void)
QLocale locale(void)
QPoint mapFrom(QWidget *parent, QPoint)
QPoint mapFromGlobal(QPoint)
QPoint mapFromParent(QPoint)
QPoint mapTo(QWidget *parent, QPoint)
QPoint mapToGlobal(QPoint pos)
QPoint mapToParent(QPoint pos)
QRegion mask(void)
int maximumHeight(void)
QSize maximumSize(void)
int maximumWidth(void)
int minimumHeight(void)
QSize minimumSize(void)
int minimumWidth(void)
void move(int x, int y)
QWidget *nativeParentWidget(void)
QWidget *nextInFocusChain(void)
QRect normalGeometry(void)
void overrideWindowFlags(int flags)
QPalette palette(void)
QWidget *parentWidget(void)
QPoint pos(void)
QWidget *previousInFocusChain(void)
QRect rect(void)
void releaseKeyboard(void)
void releaseMouse(void)
void releaseShortcut(int id)
void removeAction(QAction *action)
void render(QPaintDevice *target, QPoint,QRegion, int)
void repaint(int x, int y, int w, int h)
void resize(int w, int h)
bool restoreGeometry(QByteArray)
QByteArray saveGeometry(void)
void scroll(int dx, int dy)
void setAcceptDrops(bool on)
void setAccessibleDescription(QString)
void setAccessibleName(QString)
void setAttribute(int attribute, bool on)
void setAutoFillBackground(bool enabled)

71.19. Configuration file for the Qt Framework 794