Home AESAES Process libraryProcess library Resource libraryResource library

8.20 Property library

This library contains special functions, which are only available on FreeGEM.

• prop_del Deletes a setting from global properties file
• prop_get Gets settings from global properties file
• prop_gui_get Obtains GUI options
• prop_gui_set Sets GUI options
• prop_put Saves setting to global properties file

See also: About the AES

8.20.1 prop_del

Name: »Property delete« - Delete setting from the GEM configuration file.
 
Opcode: 1012
 
Syntax: int16_t prop_del ( int8_t *program, int8_t *section, int16_t options );
 
Description: The call prop_del serves for deleting settings from the global settings file of the AES. The following apply:
 
Parameter Meaning
   
program Name that identifies the program. It should be formed of one or more words separated by dots - for example, the DEMO sample uses "PTK.DEMO".
section Name of the field to delete. Again, this should be one or more words separated by dots. DEMO uses "Pen.shade", "Pen.colour" and "Pen.size".
options Current user (0) or all users (1). Use 0 if possible although multiple user profiles is not yet supported.
Return value:  0 = Property delete successfully
 1 = Property was not found
-1 = File I/O error

 
Availability: This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init(xbuf) and check that bit 1 of xbuf.abilities is set (ABLE_PROP).
 
Group: Property library
 
See also: Binding   prop_get   prop_put
 

8.20.1.1 Bindings for prop_del

C: int16_t prop_del ( int8_t *program, int8_t *section, int16_t options );
 
Binding:
  
int16_t prop_del (int8_t *program, int8_t *section, int16_t options )
{
   int_in[0]  = options;
   addr_in[0] = program;
   addr_in[1] = section;

   return ( crys_if(1012) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 1012 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 2 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] options
addr_in addr_in[0] program
addr_in+4 addr_in[1] section
int_out int_out[0] Return value

8.20.2 prop_get

Name: »Property get« - Read setting from the GEM configuration file.
 
Opcode: 1010
 
Syntax: int16_t prop_get ( int8_t *program, int8_t *section, int8_t *buffer, int16_t buflen, int16_t options );
 
Description: The call prop_get serves for reading settings from the global settings file of the AES. The following apply:
 
Parameter Meaning
   
program Name that identifies the program. It should be formed of one or more words separated by dots - for example, the DEMO sample uses "PTK.DEMO".
section Name of the field to retrieve. Again, this should be one or more words separated by dots. DEMO uses "Pen.shade", "Pen.colour" and "Pen.size".
buffer Address of the buffer to which the information will be written.
buflen Size of buffer, including the terminating 0.
options Current user (0) or all users (1). Use 0 if possible although multiple user profiles is not yet supported.
Return value:  0 = Property read successfully
 1 = Property was not found
-1 = File I/O error
-2 = Not enough memory
 
Availability: This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init(xbuf) and check that bit 1 of xbuf.abilities is set (ABLE_PROP).
 
Group: Property library
 
See also: Binding   prop_del   prop_put
 

8.20.2.1 Bindings for prop_get

C: int16_t prop_get ( int8_t *program, int8_t *section, int8_t *buffer, int16_t buflen, int16_t options );
 
Binding:
  
int16_t prop_get (int8_t *program, int8_t *section, int8_t *buffer,
                  int16_t buflen, int16_t options )
{
   int_in[0]  = options;
   int_in[1]  = buflen;
   addr_in[0] = program;
   addr_in[1] = section;
   addr_in[2] = buffer;

   return ( crys_if(1010) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 1010 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] options
int_in+2 int_in[1] buflen
addr_in addr_in[0] program
addr_in+4 addr_in[1] section
addr_in+8 addr_in[2] buffer
int_out int_out[0] Return value

8.20.3 prop_gui_get

Name: »GUI options get« - Gets the value of a GUI option.
 
Opcode: 1013
 
Syntax: int16_t prop_gui_get ( int16_t option );
 
Description: The call prop_gui_get returns the value of the given option, or zero if the option is out of range. The following apply:
 
option Meaning
   
0 Count of available options (currently returns 5; valid values are 0-4).
1 3D objects have square corners (0); otherwise rounded corners.
2 Window frames follow GEM/2 style (0); otherwise GEM/5 style.
3 GEM emulation mode:
0 - GEM/1
1 - Atari GEM
2 - FreeGEM
4 Menu flags:
Bit 0 - "Name of Desk" menu is the current program name (0) or "Desk" (1)
Bit 1 - "Desk" menu is on the right (0) or on the left (1)
Return value: Value of the requested option, or 0 if option is out of range.
 
Availability: This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init(xbuf) and check that bit 5 of xbuf.abilities is set (ABLE_PROP2).
 
Group: Property library
 
See also: Binding   prop_gui_set
 

8.20.3.1 Bindings for prop_gui_get

C: int16_t prop_gui_get ( int16_t option );
 
Binding:
  
int16_t prop_gui_get ( int16_t option )
{
   int_in[0]  = option;

   return ( crys_if(1013) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 1013 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] option
int_out int_out[0] Return value

8.20.4 prop_gui_set

Name: »GUI options set« - Sets the value of a GUI option.
 
Opcode: 1014
 
Syntax: int16_t prop_gui_set ( int16_t option, int16_t value );
 
Description: The call prop_gui_set changes the given option. The following apply:
 
option Meaning
   
0 Cannot be set. Return 0.
1 3D objects: set square corners (0); otherwise rounded corners.
2 Window frames: set GEM/2 style (0); otherwise GEM/5 style. Takes effect when a new program is loaded.
3 Set the GEM emulation mode:
0 - GEM/1
1 - Atari GEM
2 - FreeGEM

Currently, FreeGEM supports only modes 0 and 2 (they are the same). The variable is set to 0 if the desired mode is not available, or to the requested mode if it is available.
4 Set menu flags:
Bit 0 - Name of "Desk" menu is the current program name (0) or "Desk" (1)
Bit 1 - "Desk" menu is on the right (0) or on the left (1)
Return value: Returns the value used, which may not be the same as the requested value.
 
Availability: This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init(xbuf) and check that bit 5 of xbuf.abilities is set (ABLE_PROP2).
 
Group: Property library
 
See also: Binding   prop_gui_get
 

8.20.4.1 Bindings for prop_gui_set

C: int16_t prop_gui_set ( int16_t option, int16_t value );
 
Binding:
  
int16_t prop_gui_set ( int16_t option, int16_t value )
{
   int_in[0]  = option;
   int_in[1]  = value;

   return ( crys_if(1014) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 1014 # Function opcode
control+2 control[1] 2 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 0 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] option
int_in+2 int_in[1] value
int_out int_out[0] Return value

8.20.5 prop_put

Name: »Property put« - Write setting to the GEM configuration file.
 
Opcode: 1011
 
Syntax: int16_t prop_put ( int8_t *program, int8_t *section, int8_t *buffer, int16_t options );
 
Description: The call prop_put serves for writing settings to the global settings file of the AES. The following apply:
 
Parameter Meaning
   
program Name that identifies the program. It should be formed of one or more words separated by dots - for example, the DEMO sample uses "PTK.DEMO". Program names starting with "GEM." should be avoided to avoid a conflict with GEM itself.
section Name of the field to store. Again, this should be one or more words separated by dots. DEMO uses "Pen.shade", "Pen.colour" and "Pen.size".
buffer Address of the buffer containing the information to write (NULL-terminated, without carriage returns or linefeeds).
options Current user (0) or all users (1). Use 0 if possible although multiple user profiles is not yet supported.

Note: prop_get will remove any leading spaces from returned values; so to write a string value that may start with spaces, quotation marks must be added before calling prop_put and the quotation marks should be removed after the prop_get.
 
Return value:  0 = Property write successfully
-1 = File I/O error
-2 = Not enough memory
 
Availability: This call is a compile-time option in recent FreeGEM versions. To check for this feature, use appl_init(xbuf) and check that bit 1 of xbuf.abilities is set (ABLE_PROP).
 
Group: Property library
 
See also: Binding   prop_del   prop_get
 

8.20.5.1 Bindings for prop_put

C: int16_t prop_put ( int8_t *program, int8_t *section, int8_t *buffer, int16_t options );
 
Binding:
  
int16_t prop_put (int8_t *program, int8_t *section, int8_t *buffer,
                  int16_t options )
{
   int_in[0]  = options;
   addr_in[0] = program;
   addr_in[1] = section;
   addr_in[2] = buffer;

   return ( crys_if(1011) );
}
GEM-Arrays:
 

Address Element Contents
control control[0] 1011 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 1 # Entry in int_out
control+6 control[3] 3 # Entry in addr_in
control+8 control[4] 0 # Entry in addr_out
int_in int_in[0] options
addr_in addr_in[0] program
addr_in+4 addr_in[1] section
addr_in+8 addr_in[2] buffer
int_out int_out[0] Return value
Home AESAES Process libraryProcess library Resource libraryResource library