FlipSide A.E. Icon

AEEncoder

Derived From: none
Declared in: AEEncoder.h
Library: libaeencoder.a
Summary: more...
AEEncoder is the base class for all encoders used by FlipSide A.E. There are a maximum of 5 methods that an AEEncoder subclass should implement. Of those five, only Encode() is required. The AEEncoder baseclass does several things for you.
  1. Reads in saved settings upon creation, and if there are no settings saved, calls the LoadDefault* methods to load the default values.
  2. Saves settings before the object is destroyed. Settings are saved in: <USER SETTINGS DIRECTORY>/FlipSide Software/FlipSide A.E./<ADDON NAME> Settings
  3. Provides a utility method FindExecutable() to find a program on any queryable drive on the users system.
Documentation: You should provide an html document with a production add-on. It should be named the same as your Add-on's name with a .html extension. FlipSide A.E. may soon be providing a way to pull up your help file from the GUI, and these are the most likely requirements. It should be installed into the same file structures as the ones that shipped with FlipSide A.E. Feel free to use them as a template. In fact we encourage it. You may also use the flipsideae_icon.gif file as your BeBits icon. If you would like to notify me of its publication we will be happy to link to it from both the FlipSide A.E. hompepage, and it's BeBits page. We are also here to help in any way we can to make your encoder work as well as possible.

Constructor and Destructor


FlipSide A.E. Icon

AEEncoder()

AEEncoder(const char* encoderName)


Sets the encoder add-ons name, and loads saved settings. If your Add-on requires the service of external applications (e.g. command line apps) you should use the FindExecutable() method to get the full path for the application. This should be done in the constructor and not in Encode(). If you can't find the application, set the protected member error to FSS_EXE_NOT_FOUND.

FlipSide A.E. Icon

~AEEncoder()

~AEEncoder()


Saves settings to the users settings directory, and then deletes the objects allocated memory.

Member Functions


FlipSide A.E. Icon

CheckForCancel()

protected bool CheckForCancel()


Returns true if the user has canceled encoding.

FlipSide A.E. Icon

Encode()

int32 Encode(BMessage* encodeMessage)


This is the meat of a FlipSide A.E. Encoder Add-on. encodeMessage is a pointer to a FSS_ENCODE Message. The details of the contents of the message are described below. Basicly, it contains the path to the input file, the path to the output file, desired attribute values, and a pointer to a BMessenger for the status bar. So here are the rules of the game:
RETURN VALUES
B_OK Everything went great!
B_ERROR Damn! Something screwed up.
FSS_CANCEL_ENCODING What? You don't want to play anymore?
FSS_EXE_NOT_FOUND Now where did I put it?
FSS_INPUT_NOT_SUPPORTED    I can't handle this input file!

FlipSide A.E. Icon

FindExecutable()

protected int32 FindExecutable(const char* executable, char* path)


A utility method that queries all queriable drives (starting with /boot) for executable. If found, it copies the full path to the executable into path and returns B_OK. If it cannot find executable, path remains unchanged and FSS_EXE_NOT_FOUND is returned. If an error occured creating the query, B_ERROR is returned.

RETURN VALUES
B_OK We found it!
B_ERROR Ooops!
FSS_EXE_NOT_FOUND    Now where did I put it?

FlipSide A.E. Icon

GetMenu()

BMenu* GetMenu()


Returns a pointer to the encoder's menu.

FlipSide A.E. Icon

GetName()

const char* GetName()


Returns a pointer to the encoder's name.

FlipSide A.E. Icon

GetPattern(), SetPattern()

const char* GetPattern()
void SetPattern(const char* value)


These functions get and set the output file pattern for the encoder.

FlipSide A.E. Icon

InitCheck()

int32 InitCheck()


Returns the status of the initialization.

RETURN VALUES
B_OK Everything's peachy.
B_ERROR Not cool.
FSS_EXE_NOT_FOUND    Now where did I put it?

FlipSide A.E. Icon

InitEncoder(), UninitEncoder()

int32 InitEncoder()
int32 UninitEncoder()


InitEncoder() is called before a session of Encode()'s. You should only override this is you have data that should persist over an entire encoding session. This is very rare. If you do override it, you have to call AEEncoder::InitEncoder() at the beginning of your method. UninitEncoder() is called at the end of the session. It will always be called, even when a user cancels, or a call to Encode() fails. It should be used to release any resources allocated in InitEncoder().

RETURN VALUES
B_OK Sweeeeeet!
B_ERROR    Uh Oh!

FlipSide A.E. Icon

LoadDefaultPattern()

int32 LoadDefaultPattern()


The Default DefaultPattern is the empty string. I strongly suggest overriding this method to provide a sane default for the users of your add-on. The variables available to you for replacement are:

Variable Meaning
%a Artist
%n Album
%t Title
%y Year
%c Comment
%k Track
%g Genre


RETURN VALUES
B_OK Awsome!
B_ERROR    Something is really screwed.

FlipSide A.E. Icon

LoadDefaultMenu()

int32 LoadDefaultMenu()


This is the backbone of probably the coolest feature of FlipSide A.E.: encoder based settings. All you have to do is create a BMenu that contains all your settings. There are only a couple of requirements.
menu = new BMenu(GetName());


To have an option checked or unchecked when a user clicks on it (and it's not in a menu that has radiomode turned on) set the invoker message to one of type FSS_MENU_ITEM_SELECTED. FlipSide A.E. will then take care of checking and unchecking it.

RETURN VALUES
B_OK Awsome!
B_ERROR    Something is really screwed.

FlipSide A.E. Icon

SetPattern() see GetPattern()




BMessages


FlipSide A.E. Icon

FSS_ENCODE

This is the message passed to Encode().

Field Type code Description Required
"input file" B_STRING_TYPE full path to input file Yes
"output file" B_STRING_TYPE full path to output file Yes
"statusBarMessenger" B_MESSENGER_TYPE BMessenger for the Status Bar Yes
"artist" B_STRING_TYPE Artist No
"album" B_STRING_TYPE Album No
"title" B_STRING_TYPE Title No
"year" B_STRING_TYPE Year No
"Comment" B_STRING_TYPE Comment No
"track" B_STRING_TYPE Track No
"genre" B_STRING_TYPE Genre No
"genre number" B_INT32_TYPE ID3 v1.1 number for "genre" No; supplied if "genre" is.
"error" B_STRING_TYPE A clear user understandable error message to explain what went wrong. No, but should supplied if the addon returns B_ERROR.



FlipSide A.E. Icon

FSS_MENU_ITEM_SELECTED

Pass a new BMessage of this type into the constructor of a BMenuItem if you would like FlipSide A.E. to toggle checked/unchecked on the item.


FlipSide A.E. Icon

FSS_SETMAX_STATUS_BAR

You send this message if you wish to change the maximum value of the status bar.

Field Type code Description Required
"max" B_FLOAT_TYPE the desired maximum value of the status bar Yes



Add-on Function


FlipSide A.E. Icon

load_encoder()

AEEncoder* load_encoder()


This is the function FlipSide A.E. calls to get the pointer to your AEEncoder object. The code is very simple.
MyAEEncoderSubclass::MyAEEncoderSubclass() : AEEncoder("my subclass")
{
}

AEEncoder* load_encoder()
{
    return new MyAEEncoderSubclass();
}