RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


File Info Dialogue box class


A File Info dialogue object is used to display information about a file (or a directory or application) in a dialogue box.

User interface

A File Info dialogue has the following information held in its dialogue box:

FILEINFO-2.GIF

  • an indication of whether the file is modified (a textual display field with the text 'YES' or 'NO')
  • a sprite representing the file type (i.e. a sprite named file_xxx where xxx is the hex representation of the file type). If the filetype is 0x1000 a directory sprite is used, and if 0x2000 an application sprite is used.
  • the type of the file (a textual display field with the textual filetype followed by its hex value in brackets)
  • the full pathname of the file or '<untitled>' (a display field)
  • the size of the file in bytes (a display field giving the size of the file)
  • the date the file was last written to (a textual display field showing the date in '*time' format).

Application Program Interface

Attributes

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)
Manipulating a File Info object
Creating and deleting a File Info object

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.

Showing a File Info object

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
Before the File Info dialogue box is shown

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.

Setting and reading the fields of the File Info dialogue

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

File Info methods

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
FileInfo_GetWindowID 0
On entry
R0 = flags
R1 = File Info object id
R2 = 0
On exit
R0 = window object id for this File Info object
Use

This method returns the id of the underlying window object used to implement this File Info object.

C veneer

extern _kernel_oserror *fileinfo_get_window_id ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 ObjectId *window
                                               );


FileInfo_SetModified 1
On entry
R0 = flags
R1 = File Info object id
R2 = 1
R3 = value
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *fileinfo_set_modified ( unsigned int flags,
                                                ObjectId fileinfo,
                                                int modified
                                              );


FileInfo_GetModified 2
On entry
R0 = flags
R1 = File Info object id
R2 = 2
On exit
R0 = modified state (0 => UNMODIFIED_ NON-0 => modified)
Use

This method returns whether the file is indicated as modified or not.

C veneer

extern _kernel_oserror *fileinfo_get_modified ( unsigned int flags,
                                                ObjectId fileinfo,
                                                int *modified
                                              );


FileInfo_SetFileType 3
On entry
R0 = flags
R1 = File Info object id
R2 = 3
R3 = file type
On exit
R1-R9 preserved
Use

This method sets the file type to be indicated in the dialogue box.

C veneer

extern _kernel_oserror *fileinfo_set_file_type ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 int file_type
                                               );


FileInfo_GetFileType 4
On entry
R0 = flags
R1 = File Info object id
R2 = 4
On exit
R0 = file type
Use

This method returns the file type shown in the dialogue box.

C veneer

extern _kernel_oserror *fileinfo_get_file_type ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 int *file_type
                                               );


FileInfo_SetFileName 5
On entry
R0 = flags
R1 = File Info object id
R2 = 5
R3 = pointer to buffer holding filename
On exit
R1-R9 preserved
Use

This method sets the filename used in the File Info dialogue's Window. There is a limit of 256 characters on the filename length.

C veneer

extern _kernel_oserror *fileinfo_set_file_name ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 char *file_name
                                               );


FileInfo_GetFileName 6
On entry
R0 = flags
R1 = File Info object id
R2 = 6
R3 = pointer to buffer to hold filename
R4 = size of buffer to hold filename
On exit
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
Use

This method returns the current filename used in a File Info object.

C veneer

extern _kernel_oserror *fileinfo_get_file_name ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 char *buffer,
                                                 int buff_size,
                                                 int *nbytes
                                               );


FileInfo_SetFileSize 7
On entry
R0 = flags
R1 = File Info object id
R2 = 7
R3 = file size
On exit
R1-R9 preserved
Use

This method sets the file size to be indicated in the dialogue box.

C veneer

extern _kernel_oserror *fileinfo_set_file_size ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 int file_size
                                               );


FileInfo_GetFileSize 8
On entry
R0 = flags
R1 = File Info object id
R2 = 8
On exit
R0 = file size
Use

This method returns the file size shown in the dialogue box.

C veneer

extern _kernel_oserror *fileinfo_get_file_size ( unsigned int flags,
                                                 ObjectId fileinfo,
                                                 int *file_size
                                               );


FileInfo_SetDate 9
On entry
R0 = flags
R1 = File Info object id
R2 = 9
R3 = pointer to 5-byte UTC time
On exit
R1-R9 preserved
Use

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.

C veneer

extern _kernel_oserror *fileinfo_set_date ( unsigned int flags,
                                            ObjectId fileinfo,
                                            int *UTC
                                          );


FileInfo_GetDate 10
On entry
R0 = flags
R1 = File Info object id
R2 = 10
R3 = pointer to buffer to hold 5-byte UTC time
On exit
R1-R9 preserved
Use

This method returns the current UTC time used in a File Info object.

C veneer

extern _kernel_oserror *fileinfo_get_date ( unsigned int flags,
                                            ObjectId fileinfo,
                                            int *UTC
                                          );


FileInfo_SetTitle 11
On entry
R0 = flags
R1 = File Info object id
R2 = 11
R3 = pointer to text string to use
On exit
R1-R9 preserved
Use

This method sets the text which is to be used in the title bar of the given File Info dialogue.

C veneer

extern _kernel_oserror *fileinfo_set_title ( unsigned int flags,
                                             ObjectId fileinfo,
                                             char *title
                                           );


FileInfo_GetTitle 12
On entry
R0 = flags
R1 = File Info object id
R2 = 12
R3 = pointer to buffer to return the text in (or 0)
R4 = size of buffer
On exit
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
Use

This method returns the text string used in a File Info dialogue's title bar.

C veneer

extern _kernel_oserror *fileinfo_get_title ( unsigned int flags,
                                             ObjectId fileinfo,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes
                                           );


File Info events

The File Info module generates the following Toolbox events:

FileInfo_AboutToBeShown (0x82ac0)
Block
+ 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
Use

This Toolbox event is raised just before the File Info module is going to show its underlying Window object.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                show_type;
  union
  {
    TopLeft               pos;
    WindowShowObjectBlock full;
  } info;
} FileInfoAboutToBeShownEvent;


FileInfo_DialogueCompleted (0x82ac1)
Block
+ 8 0x82ac1
+ 12 flags
(none yet defined)
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} FileInfoDialogueCompletedEvent;


File Info templates

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
Underlying window template

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.

Gadgets

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)

File Info Wimp event handling

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

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015