Misc

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:
See also: DestroyTexts, PrintFloatingConversion, RegisterConversionHandler.
void DestroyTexts(void);

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.
void RegisterConversionHandler(void (*Handler)(void *, char *), void *data, const char *name);

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.
void PrintFloatingConversion(char *dest, const char *src);

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.
char *msprintf(const char *format, ...)

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.


void CguiUseIcons(const char *filename);

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.


void NameCase(char *text);

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: 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:
See also: CguiLoadImage, InitCgui.
int ScanToAscii(int scancode);

Returns the ascii-code of a scancode.


int ToUpper(int chr);

as toupper but converts also the specific Swedish characters


int SaveDatafileObject(const char *path, void *data, int type);

Saves a data file object into an existing datafile.
Parameters: Return-value: 0 if error, 1 if ok.



Back to contents