Object / Family / Application

This class is the master class for all Feelin applications. It serves as a kind of anchor for all events, either coming from the user or somewhere from the system, e.g. windows, commodities or ARexx.

An application can have any number of sub windows, these windows are the children of the application. Because the class is a subclass of the Family class, you can use the AddMember and RemMember methods to add and remove children.

Each Application uses a Display object to manage its environnement.

Attributes

Overrides

Implements

Author -- (01.00) [I.G], STRPTR

Name of the application's author.

Base -- (01.00) [I.G], STRPTR

The basename for an application. This name is used for the builtin ARexx port and for some internal file management.

A basename must neither contain spaces nor any special characters such as ":/()#?*...".

When your program is a single task application (i.e. SingleTask is TRUE), the base name will be used without further modification. Otherwise, it gets a ".1", ".2", etc. appended, depending on how many applications are already running. If you need to know the name of your ARexx port, you can query the base name attribute after the application is created.

Example

ApplicationObject,
    FA_Application_Title,        "MyCD",
    FA_Application_Version,      "$VER: MyCD 1.00 (2001/10/01)",
    FA_Application_Copyright,    "© 2001 - 2004 by Olivier LAVIALE",
    FA_Application_Author,       "Olivier LAVIALE <gofromiel@gofromiel.com>",
    FA_Application_Description,  "A simple and groovy CD Player.",
    FA_Application_Base,         "MYCD",
    ...

Copyright -- (01.00) [I.G], STRPTR

A copyright string, containing the year and the company.

Description -- (01.00) [I.G], STRPTR

Short description, about 40 characters. Shown e.g. in commodities exchange.

Display -- (01.00) [..G], FObject

Returns a pointer to the Display object created by the application on creation time to manage its environement.

You shouldn't have to get this attribute, since the same pointer is available throught the Render object shared by all the elements of a same window.

Sleep -- (01.00) [ISG], bool32

This attribute can be used to put a whole application to sleep. All windows are closed and graphic resources are freed. Depending on user settings, the application can be iconified or menufied (available as an item in the worbench menu).

You wake up an application :

Title -- (01.00) [I.G], STRPTR

This tag defines the title of an application. The title is e.g. shown in Commodities Exchange or in the Feelin preferences program.

An application title shall not contain any version information, just the pure title. Also, special characters such as ":/()#?*..." are not allowed.

You should use a quiet long and unique name for your applications. Naming it "Viewer" or "Browser" is not a wise choice.

The length of the name must not exceed 30 characters!

Version -- (01.00) [I.G], STRPTR

Define a version string for an application. This string shall follow standard version string conventions but must not contain a leading "\0".

CreateSignalHandler -- (12.00)

IFEELIN F_DoA(Obj, FM_Application_CreateSignalHandler, TAGS);

Allow classes to react on the signals of private message ports.

A class can create messages ports and react on their signals on its own without interferring with the main program. A game class could open the gameport.device and react on joystick messages, an HTML class could talk to network all on its own. All this helps to further encapsulate your program into subclasses and make it a lot more easy to maintain.

Since we're talking here about method of the Application class, it's clear that you cannot call it until you know about yours. Good places for the CreateSignalHandler / DeleteSignalHandler method are probably the GlobalConnect / GlobalDisconnect methods of your Element sub-class.

Tags

FA_SignalHandler_Method (uint32)

The method to invoke on the object defined by the FA_SignalHandler_Target tag when the requested signals arrive, or a timer event occurs.

FA_SignalHandler_Micros (uint32)
FA_SignalHandler_Seconds (uint32)

Each Application object has a builtin timer. You can use it instead of managing your own by defining one of these tags. By using the builtin timer, you avoid the problem of having each instance of your object allocating a signal bit. Timer handlers are not different that signal handlers.

FA_SignalHandler_Signals (bits32)

Signals you wish to be notified on. You can set more than one bit here. This tag is ignore if either FA_SignalHandler_Micros or FA_SignalHandler_Seconds tag.

FA_SignalHandler_Target (FObject)

Object on which the method defined with the FA_SignalHandler_Method tag will be invoked if one of the signals arrives.

Result

A signal handle, which must be used to remove the handler. You must match each CreateSignalHandler method with exatly one DeleteSignalHandler method.

Example

application-createsignalhandler 
struct LocalObjectData
{
    F_MEMBER_ELEMENT_PUBLIC;
    F_MEMBER_AREA_PUBLIC;

    APTR                            timer_handler;
};

enum  {

      FV_METHOD_STROBO

      };

F_METHOD(bool32, mShow)
{
    struct LocalObjectData *LOD = F_LOD(Class,Obj);

    if (F_SUPERDO() == FALSE)
    {
        return FALSE;
    }

    if (!LOD->timer_handler)
    {
        LOD->timer_handler = (APTR) IFEELIN F_Do
        (
            _element_application, FM_Application_CreateSignalHandler,

            FA_SignalHandler_Target, Obj,
            FA_SignalHandler_Method, F_METHOD_ID(STROBO),
            FA_SignalHandler_Micros, 30000,

            TAG_DONE
        );
    }

    if (!LOD->timer_handler)
    {
        return FALSE;
    }

    return TRUE;
}

F_METHOD(uint32, mHide)
{
    struct LocalObjectData *LOD = F_LOD(Class,Obj);

    if (LOD->timer_handler)
    {
        IFEELIN F_Do(_element_application, FM_Application_DeleteSignalHandler, LOD->timer_handler);

        LOD->timer_handler = NULL;
    }

    return F_SUPERDO();
}

F_METHOD(bool32, mStrobo)
{
   IFEELIN F_Draw(Obj, FF_Draw_Update);

   // If we return FALSE the timer event won't be requested again
   
   return TRUE;
}

DeleteSignalHandler -- (12.00)

IFEELIN F_Do(Obj, FM_Application_DeleteSignalHandler, APTR Handler);

Delete a signal (or timer) handler.

Your trigger method is no longer called after you have deleted the handler.

Inputs

An handle return by the CreateSignalHandler method.

PushMethod -- (07.00)

IFEELIN F_Do(Obj, FM_Application_PushMethod, FS_Application_PushMethod, ...);

Usually, you may not talk to an application from two tasks at the same time. This method provides some kind of solution for this problem.

This (and only this) method may be called from a second task. It takes another method as parameter and puts it onto a private stack of the application object. The pushed method is read within the Run method and executed in the context of the current task.

The main purpose of this method is to be sure that the code it execute is executed from the main application loop, the safer place of the application.

The inputs are similar to the Notify method.

Inputs

Target (FObject)

The target object on which to perform the pushed method.

Method (uint32)

The method to invoke on the target object.

Count (uint32)

The number of following arguments.

...

Arguments.

Result

The method returns TRUE if the message was successfuly pushed.

Run -- (06.00)

IFEELIN F_Do(Obj, FM_Application_Run);

Launch the application.

Once your application tree has been successfully created, all you need to do to see all your dreams come true is to launch the application with the Run method. The application's process is used to handle signals, as well as many system events. It really is the heart of your application, not a single window may open before this method is called.

Note that the method won't exit until the application receives the Shutdown method.

Example

FObject app, win;

app = ApplicationObject,
    Child, win = WindowObject,
        FA_Window_Title, "Feelin : Hello World !",
        FA_Window_Open, TRUE,

        Child, Button("Hello World !"),
    End,
End;

if (app)
{
    F_Do(win, FM_Notify, FA_Window_CloseRequest, TRUE,
         app, FM_Application_Shutdown, 0);

    F_Do(app, FM_Application_Run);

    F_DisposeObj(app);
}

Shutdown -- (06.00)

IFEELIN F_Do(Obj, FM_Application_Shutdown);

Returns from the Run method.

The method can safely be invoked from another task.

Development