Various functions that may be of interest.
char const*const*LoadTexts(const char *fn, const char *section);
Loads a section of text from a file. Intended to be used in conjunction
with the `mktext' tool to make executables language independent
in an simple way. See readme.txt for `mktext'. The "text module" doesn't
really do very much, but it does it the right way...
LoadTexts will search for the language specified in the current
environment (i.e. allegro.cfg if no other specified). It will first
search for the language in the CGUI-section, if not found it will look
in the global section, and if not found there (or if config is not
present) it will take english.
If the language determined this way is not found in the specified file
it will look for the english language, and if that is not found it will
take a random (first).
The language name specified in the text-source may be any text (in legal
identifier form), strings will just be compared. To make use of the error
handling you it is necessary to follow the convention used in allegros
cfg-file (i.e. "en" for english, "de" for german etc).
`LoadTexts' returns a pointer to an array of strings. That array must be
indexed with the macros that you specified in the source-file, and
available in the header-file (`*.ht'), generated by
`mktext'.
Calling `LoadTexts' requesting an already loaded section, will not
consume memory (the same pointer as the first time will be returned).
Calling `LoadTexts' requesting an already loaded section, but with a new
language found in the current environment, will re-load the text. All
previously returned pointers to sections within the same file will then
be corrupt, and must be re-loaded.
Parameters:
- fn: filename to load
- section: the name of the section
See also:
DestroyTexts,
PrintFloatingConversion,
RegisterConversionHandler.
Will release memory allocated for all texts loaded by LoadTexts. You
don't need to call it - it will be called automatically at program exit.
See also:
LoadTexts.
Registers `Handler' and `data' as the converter for conversion-code
`name'. `Handler' will be assicated with the text string `name' and
called with `data' and a string pointer when needed. Its only task is
to put some text into the string called with, possibly with use of the
pointer `data'. The `name' shall include the <> like: "<person>".
See also:
LoadTexts,
PrintFloatingConversion.
A text specified in the source text-file, processed by `mktext' may
contain conversion codes of an extended format. These codes look like
%<text> (where `text' may be any text) and may be embedded in the
source-string like the C-standard conversion codes. The difference is
that since the conversion is name-referenced multiple occurances of
conversion codes in the same string may be put permutated order in
different languages.
`PrintFloatingConversion' does not recognise the C standard conversion
codes.
If a no handler is associated with the "<xx>" in "%<xx>" (which
may be the case if you accidently misspell the text), the text
"<xx>" will be printed instead.
Example: Suppose that the row is in you source-text-file:
SIZE_ERROR_TEXT "%<name> has to many (%<nr_things>) things|OK"
Suppose the following fuctions beeing registered for "<name>"
and "<nr_things>":
void name_handler(void *data, char *s)
{
/* suppose data points to a string containing the desired name */
strcpy(s, data);
}
void thing_handler(void *data, char *s)
{
int *i = data;
/* suppose data points to an integer containing the desired value */
sprintf(s, "%d", *i);
}
The above functions will be called whith a pointer to proper location
into the destination string when needed while `PrintFloatingConversion'
is executing in the below statement:
char string[1000];
. . .
PrintFloatingConversion(string, txt[SIZE_ERROR_TEXT]);
Req(string);
This call to `PrintFloatingConversion' will result in the following
string printed by `Req' (imagine the name to be "John Smith" and
value to be 13):
John Smith has to many (13) things
See also:
LoadTexts,
RegisterConversionHandler.
This function works as sprintf, except that the print buffer is not an
input parameter, but instead a return value. The returned pointer is
allocated dymanically and the caller is responsible for freeing the
memory.
Use this function if you want to use other than the default icons for the
built in dialogues in CGUI. 'filename' must be a dat-file, and the
datafile objects (i.e. the icons) must be named exactely as in the
default icons which you can find in the resource directory.
This function converts one string to lowercase, except from the initial
letter of each word. A word is a sub-string that follows a space, a tab,
or a minus-sign '-'.
int AddClock(int x, int y, int options);
Creates a clock at desired position. The time is shown as HH:MM:SS or
HH:MM. Which one to use is checked in the config-file. If the value can
not be retrieved from the config file the default is HH:MM.
The user can start a dialogue (if not suppressed by flag, see below)
to adjust the clock settings (minute or second based showing and, in
case the platform supports it, modifying the time). User modifications
are always stored into the current config file.
The `options' parameter can be either of:
- CLOCK_NO_DIALOGUE - The dialogue will not be available for the user.
The config file to store and read from is the "current config", so if
you adds multiple clocks they will all get the same setting.
The return value is the id of the clock object.
void Sound(int freq, int duration);
Starts the internal pc-speaker immediately with the sound of "freq".
The speaker will run in the background and is stopped after "duration"
milliseconds. Only available on DJGPP-platform.
void ScrMode(void (*CallBack)(void));
This function will make a dialogue that lets the user select new screen
settings of resolution and colour depth.
If the changed are done by the user all images that has been
pre-loaded by `CguiLoadImage', will be re-loaded to make it possible for CGUI
to display them properly.
After a selection the new settings will be stored into the
current configuration file. To make CGUI using these stored settings
automatically, you should pass 0 for the settings when calling InitCgui.
Parameter:
- CallBack: If this parameter is not NULL, the function 'CallBack'
will be called after the user has made changes. This may be useful
if you for example wants to store it in some other environment.
Use the Allegro-macros SCREEN_W and SCREEN_H or
bitmap_color_depth(screen) to determine the new settings.
See also:
CguiLoadImage,
InitCgui.
Returns the ascii-code of a scancode.
as toupper but converts also the specific Swedish characters
Saves a data file object into an existing datafile.
Parameters:
- path: Path pointing into an existing datafile. The path must follow
the allegro convention for specification of a data file object. i.e.
[optional absolute or relative path]filename.dat#[optional path
within the datafile]objectname
The possible "path within the datafile" must exist (sub-datafiles will
not be automatically added).
If an object with the specified name exists it will be replaced. If
there are several objects with this name (the datafiles themselves has
no restriction of multiple names) the first one will be replaced.
- data: a pointer to the data to be stored.
- type: the type of the object to be stored, e.g. DAT_BITMAP. See
grabber.txt in allegro/tools for more info about data files.
Return-value: 0 if error, 1 if ok.
Back to contents