|
www.riscos.com Technical Support: |
A File Info dialogue has the following information held in its dialogue box:
A File Info object has the following attributes which are specified in its object template and can be manipulated at run-time by the client application:
| Attributes | Description | |
|---|---|---|
| flags | Bit | Meaning |
| 0 | when set, this bit indicates that a FileInfo_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | |
| 1 | when set, this bit indicates that a FileInfo_DialogueCompleted event should be raised when the File Info object has been removed from the screen. | |
| File Info title | alternative title to use instead of 'About this file' (0 means use default title) | |
| max title length | this gives the maximum length in bytes of title text which will be used for this object | |
| modified | an indication as to whether the file is to be marked as modified from creation | |
| filetype | a word giving the RISC OS filetype | |
| filename | the initial filename to use in the dialogue box (if this field is 0, then the string '<untitled>' is used | |
| filesize | size of the file in bytes | |
| date | a 5-byte UTC time | |
| window | the name of an alternative window template to use instead of the default one (0 means use default) | |
A File Info object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A File Info object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for File Info objects.
When a File Info object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:
| Show type | Position | ||
|---|---|---|---|
| 0 (default) | the underlying window is shown at the last place shown on the screen, or the coordinates given in its template, if it has not already been shown | ||
| 1 (full spec) | R3 + 0 | visible area minimum x coordinate | |
| R3 + 4 | visible area minimum y coordinate | ||
| R3 + 8 | visible area maximum x coordinate | ||
| R3 + 12 | visible area maximum y coordinate | ||
| R3 + 16 | scroll x offset relative to work area | ||
| R3 + 20 | scroll y offset relative to work area | ||
| R3 + 24 | Wimp window handle of window to open behind | ||
| -1 | means top of stack | ||
| -2 | means bottom of stack | ||
| -3 | means the window behind the Wimp's backwindow | ||
| 2 (topleft) | R3 + 0 | visible area minimum x coordinate | |
| R3 + 4 | visible area minimum y coordinate | ||
When SWI Toolbox_ShowObject is called, a FileInfo_AboutToBeShown Toolbox event is raised, if the appropriate bit is set in the File Info dialogue object's flags word. This enables the client to set any of the dialogue box's fields before it is displayed.
All of the display fields in a File Info dialogue can be set and read dynamically at run-time. The sprite displayed in the dialogue box depends on the value of the filetype field.
The methods used to do this are:
FileInfo_SetModified
FileInfo_GetModified
FileInfo_SetFileType
FileInfo_GetFileType
FileInfo_SetFileName
FileInfo_GetFileName
FileInfo_SetFileSize
FileInfo_GetFileSize
FileInfo_SetDate
FileInfo_GetDate
The following methods are all invoked by calling SWI Toolbox_ObjectMiscOp with:
| R0 | holding a flags word |
| R1 | being a File Info Dialogue object id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 0 |
| R0 | = | window object id for this File Info object |
This method returns the id of the underlying window object used to implement this File Info object.
extern _kernel_oserror *fileinfo_get_window_id ( unsigned int flags,
ObjectId fileinfo,
ObjectId *window
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 1 |
| R3 | = | value |
| R1-R9 preserved |
This method sets whether the file is to be indicated as modified or not. If the value passed in R3 is 0, this indicates that the file is not modified; any other value in R3 means the file is modified.
extern _kernel_oserror *fileinfo_set_modified ( unsigned int flags,
ObjectId fileinfo,
int modified
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 2 |
R0 = modified state (0  UNMODIFIED_ NON-0 modified)
|
This method returns whether the file is indicated as modified or not.
extern _kernel_oserror *fileinfo_get_modified ( unsigned int flags,
ObjectId fileinfo,
int *modified
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 3 |
| R3 | = | file type |
| R1-R9 preserved |
This method sets the file type to be indicated in the dialogue box.
extern _kernel_oserror *fileinfo_set_file_type ( unsigned int flags,
ObjectId fileinfo,
int file_type
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 4 |
| R0 | = | file type |
This method returns the file type shown in the dialogue box.
extern _kernel_oserror *fileinfo_get_file_type ( unsigned int flags,
ObjectId fileinfo,
int *file_type
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 5 |
| R3 | = | pointer to buffer holding filename |
| R1-R9 preserved |
This method sets the filename used in the File Info dialogue's Window. There is a limit of 256 characters on the filename length.
extern _kernel_oserror *fileinfo_set_file_name ( unsigned int flags,
ObjectId fileinfo,
char *file_name
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 6 |
| R3 | = | pointer to buffer to hold filename |
| R4 | = | size of buffer to hold filename |
| R4 | = | size of buffer required to hold filename (if R3 was 0) else buffer pointed at by R3 holds filename R4 holds number of bytes written to buffer |
This method returns the current filename used in a File Info object.
extern _kernel_oserror *fileinfo_get_file_name ( unsigned int flags,
ObjectId fileinfo,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 7 |
| R3 | = | file size |
| R1-R9 preserved |
This method sets the file size to be indicated in the dialogue box.
extern _kernel_oserror *fileinfo_set_file_size ( unsigned int flags,
ObjectId fileinfo,
int file_size
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 8 |
| R0 | = | file size |
This method returns the file size shown in the dialogue box.
extern _kernel_oserror *fileinfo_get_file_size ( unsigned int flags,
ObjectId fileinfo,
int *file_size
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 9 |
| R3 | = | pointer to 5-byte UTC time |
| R1-R9 preserved |
This method sets the date string used in the File Info dialogue's window. The Territory Manager is used to convert the UTC time into a time string.
extern _kernel_oserror *fileinfo_set_date ( unsigned int flags,
ObjectId fileinfo,
int *UTC
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 10 |
| R3 | = | pointer to buffer to hold 5-byte UTC time |
| R1-R9 preserved |
This method returns the current UTC time used in a File Info object.
extern _kernel_oserror *fileinfo_get_date ( unsigned int flags,
ObjectId fileinfo,
int *UTC
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 11 |
| R3 | = | pointer to text string to use |
| R1-R9 preserved |
This method sets the text which is to be used in the title bar of the given File Info dialogue.
extern _kernel_oserror *fileinfo_set_title ( unsigned int flags,
ObjectId fileinfo,
char *title
);
| R0 | = | flags |
| R1 | = | File Info object id |
| R2 | = | 12 |
| R3 | = | pointer to buffer to return the text in (or 0) |
| R4 | = | size of buffer |
| R4 | = | size of buffer required to hold the text (if R3 was 0) else Buffer pointed to by R3 contains title text R4 holds number of bytes written to buffer |
This method returns the text string used in a File Info dialogue's title bar.
extern _kernel_oserror *fileinfo_get_title ( unsigned int flags,
ObjectId fileinfo,
char *buffer,
int buff_size,
int *nbytes
);
The File Info module generates the following Toolbox events:
| + 8 | 0x82ac0 |
| + 12 | flags (as passed in to Toolbox_ShowObject |
| + 16 | value which will be passed in R2 to ToolBox_ShowObject |
| + 20... | block which will be passed in R3 to ToolBox_ShowObject for the underlying dialogue box |
This Toolbox event is raised just before the File Info module is going to show its underlying Window object.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} FileInfoAboutToBeShownEvent;
| + 8 | 0x82ac1 |
| + 12 | flags (none yet defined) |
This Toolbox event is raised after the File Info object has been hidden, either by the user clicking outside the dialogue box or pressing Escape. It allows the client to tidy up its own state associated with this dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} FileInfoDialogueCompletedEvent;
The layout of a File Info template is shown below. Fields which have types MsgReference and StringReference are those which will require relocation when they are loaded from a resource file. If the template is being constructed in memory, then these fields should be real pointers (i.e. they do not require relocation).
For more details on relocation, see Resource File Formats.
| Field | Size in bytes | Type |
|---|---|---|
| flags | 4 | word |
| title | 4 | MsgReference |
| modified | 4 | word |
| filetype | 4 | word |
| filename | 4 | MsgReference |
| filesize | 4 | word |
| date | 8 | 2 words |
| window | 4 | StringReference |
The window object used to implement a File Info dialogue has the following characteristics. These must be reproduced if the Window is replaced by a client-specified alternative Window template:
Title bar must be indirected.
Component ids are derived by adding to 0x82ac00.
| Component id | Details |
|---|---|
| 0 | Display Field (date) |
| 1 | Display Field (size in bytes) |
| 2 | Display Field (filename) |
| 3 | Display Field (filetype) |
| 4 | Display Field (modified field) |
| 5 | Button gadget (indirected sprite used to display icon for file type) |
| 6 | Label (date) |
| 7 | Label (size) |
| 8 | Label (modified) |
| 9 | Label (type) |
| Wimp event | Action |
|---|---|
| Open Window | Request show the dialogue box |
| Key Click | if Escape, then cancel this dialogue. |
| User Message | Window_HasBeenHidden hide the dialogue box |