Firefly profile tutorial

[aaronmielke]

*****************
Firefly Profile Tutorial
5/3/04
*****************

Please reply to this thread if you have any questions

-------
Summary
-------
This tutorial is for advanced users only. It assumes that the user has existing knowledge of technologies such as XML and Windows attributes. The Profile system in Firefly is set up so that a user can create/edit profiles to control any Windows application with the Firefly remote. Each profile maps a group of Firefly buttons to a series of Actions to perform whenever that button is pressed. In addition, each profile contains Identifiers that specify what application it is the mapping for.

---------
Hierarchy
---------
There is a basic hierarchy for profiles in Firefly. Whenever a button is pressed, Firefly first checks all the profiles it has until it finds the appropriate profile and executes it. If no matching profile is found, Firefly then executes whatever is defined in the Default.xml profile. In the event that the appropriate profile or the default profile does not have a mapping for the button that was pressed, Firefly executes whatever it finds in the Global.xml profile. In short, Firefly executes either the default profile or the profile associated with the currently active application. If no action is performed it then executes the actions in the Global.xml profile if any are mapped for the button that is pressed.

However, when in Mouse Mode (entered by pressing the "Mouse" button on the remote), Firefly does not search the profiles or execute the Default.xml profile. Instead, it executes the Mouse.xml profile, and if no mapping is found, it then executes the Global.xml profile.

-------------------
Format of a Profile
-------------------
A profile is an XML document structured in the following manner:

<Profile Type="Snapstream.Firefly.Core.Profile" Name="PROFILE_NAME" ShowOSD="True/False">
<Identifier ClassName="CLASS_NAME" WindowText="WINDOW_TEXT" FileName="FILENAME" ClassNameComparer=�CLASS_NAME_COMPARER� WindowTextComparer = “WINDOW_TEXT_COMPARER� FileNameComparer=�FILE_NAME_COMPARER� />
<Identifier ... />
<Identifier ... />

...

<Actions Button="FIREFLY_BUTTON" Description="DESCRIPTION">
*LIST OF ACTIONS*
</Actions>
<Actions Button="FIREFLY_BUTTON" Description="DESCRIPTION">
*LIST OF ACTIONS*
</Actions>
<Actions Button="FIREFLY_BUTTON" Description="DESCRIPTION">
*LIST OF ACTIONS*
</Actions>

...

</Profile>

The "Button" attribute of the "Actions" XML tag corresponds to a Firefly Button. The valid values for a Firefly button are:

Close, Maximize, Play, Pause, Stop, FastForward, Rewind, SkipForward, SkipBack, Record, Number0, Number1, Number2, Number3, Number4, Number5, Number6, Number7, Number8, Number9, ChannelUp, ChannelDown, ChannelRecall, ChannelEnter, VolumeUp, VolumeDown, Mute, Info, Options, Menu, Exit, OK, Firefly, Up, Down, Left, Right, Music, Photos, DVD, TV, Video, Help, Mode, A, B, C, D

-----------
Identifiers
-----------
For each profile, if any one of the Identifiers match the window, the profile is executed. An Identifier is a standalone XML element with no closing tag. It must be named "Identifier" and it has the following attributes:

Text:
ClassName - This is the Windows class name associated with the window to be controlled.
WindowText - This is the text that is displayed on the window's title bar.
FileName - This is the file name of the program associated with the window.
Comparers:
For each Text attribute (ClassName, WindowText, FileName) there is an associated comparer value that tells Firefly how to match the text in the profile’s xml with the values returned from the application (ClassNameComparer, WindowTextComparer, FileNameComparer). A comparer can be one of 8 values:
Exact: Must be exactly the same characters including case.
CaseInsensitiveExact: Must be exactly the same characters now including case.
Contains: The text in the profile xml must be contained inside the value returned from the application, including case.
CaseInsensitiveContains The text in the profile xml must be contained inside the value returned from the application, not including case.
StartsWith: The value returned from the application must start with the text in the profile xml, including case.
CaseInsensitiveStartsWith: The value returned from the application must start with the text in the profile xml, not including case.
EndsWith: The value returned from the application must end with the text in the profile xml, including case.
CaseInsensitiveEndsWith: The value returned from the application must end with the text in the profile xml, not including case.
The default comparer for “ClassName� and “WindowText� is “Contains� while the default comparer for “FileName� is “CaseInsensitiveContains�. Comparers are mainly used to refine the identifier information and to prevent false positives.
If you specify more than one application identifier, matching is done using AND logic. For example, if you specify the ClassName as "WinDVDClass" and the Window Text as "InterVideo WinDVD Platinum 5", then the target application must contain both matching ClassName and WindowText to produce a match. You can supply from one to three identifier attributes for each identifier tag.

Use the included AppIdentifier.exe (by default, located in C:\program files\SnapStream Media\firefly) to determine these identifiers for any given application. To use this application, load AppIdentifier.exe and then switch to your target application. Then switch directly back to AppIdentifier.exe and each of the corresponding fields will contain the values for the target application.

-------
Actions
-------
The list of Actions determines what happens when a button is pressed. There are 14 types of Actions. Each one has the following format:

<ActionName *list of attributes* />

Every action has a "ActivationState" attribute that determines when to perform the Action. It can be any of the following values:

Down - Only performs the Action on the initial press of the button.
DownRepeat - Performs the Action on the initial press and repeats the action over and over while the button is held down.
Repeat - Only performs the Action after the button has been held down.
Up - Only performs the Action when the button is let go.

If this attribute is missing, the Action assumes DownRepeat by default.

---------
KeyAction
---------
This is the most common Action. It executes anywhere from 1 to a series of keyboard keypresses. It has the following attribute:

Keys - This is a series of KeyStrokes that can be mapped to. Valid values can be found here:
http://msdn.microsoft.com/library/de...classtopic.asp

Example:

<KeyAction Keys="C" ActivationState="DownRepeat" />

------------
LaunchAction
------------
This Action is used to map a Firefly Button to an application that is to be launched. It has the following attributes:

Program - The path and executable to be launched when the Action is executed.

Arguments - Command Line arguments to be passed in when the program is launched.

Description - A simple description of the program.

Example:

<LaunchAction Button="TV" Program="C:\wtlpvsapp.exe" Arguments="-mode FS" Description="Beyond TV" ActivationState="Down" />

-----------
MouseAction
-----------
Controls the mouse on the screen. Typically, this should be reserved for Mouse Mode only. It has the following attribute:

Type - This value tells the mouse to either move in a direction, or click a button. The valid values are: Up, Down, Left, Right, UpLeft, UpRight, DownLeft, DownRight, ClickLeft, ClickRight, DoubleClickLeft, DoubleClickRight

Example:

<MouseAction Type="ClickLeft" />

-----------------
PostMessageAction
-----------------
This Action is used to post Windows Messages to the current window. It has the following attributes:

Message - The actual message to be sent to the window. The valid values are: CREATE, DESTROY, MOVE, SIZE, ACTIVATE, SETFOCUS, KILLFOCUS, ENABLE, SETREDRAW, SETTEXT, GETTEXT, GETTEXTLENGTH, PAINT, CLOSE, QUERYENDSESSION, QUIT, QUERYOPEN, ERASEBKGND, SYSCOLORCHANGE, ENDSESSION, SHOWWINDOW, WININICHANGE, DEVMODECHANGE, ACTIVATEAPP, FONTCHANGE, TIMECHANGE, CANCELMODE, SETCURSOR, MOUSEACTIVATE, CHILDACTIVATE, QUEUESYNC, GETMINMAXINFO, PAINTICON, ICONERASEBKGND, NEXTDLGCTL, SPOOLERSTATUS, DRAWITEM, MEASUREITEM, DELETEITEM, VKEYTOITEM, CHARTOITEM, SETFONT, GETFONT, SETHOTKEY, GETHOTKEY, QUERYDRAGICON, COMPAREITEM, COMPACTING, COMMNOTIFY, WINDOWPOSCHANGING, WINDOWPOSCHANGED, POWER, COPYDATA, CANCELJOURNAL, NOTIFY, INPUTLANGCHANGEREQUEST, INPUTLANGCHANGE, TCARD, HELP, , USERCHANGED, NOTIFYFORMAT, CONTEXTMENU, STYLECHANGING, STYLECHANGED, DISPLAYCHANGE, GETICON, SETICON, NCCREATE, NCDESTROY,
NCCALCSIZE, NCHITTEST, NCPAINT, NCACTIVATE, GETDLGCODE, NCMOUSEMOVE, NCLBUTTONDOWN, NCLBUTTONUP, NCLBUTTONDBLCLK, NCRBUTTONDOWN, NCRBUTTONUP, NCRBUTTONDBLCLK, NCMBUTTONDOWN, NCMBUTTONUP, NCMBUTTONDBLCLK, KEYFIRST, KEYDOWN, KEYUP, CHAR, DEADCHAR, SYSKEYDOWN, SYSKEYUP, SYSCHAR, SYSDEADCHAR, KEYLAST, IME_STARTCOMPOSITION, IME_ENDCOMPOSITION, IME_COMPOSITION, IME_KEYLAST, INITDIALOG, COMMAND, SYSCOMMAND, TIMER, HSCROLL, VSCROLL, INITMENU, INITMENUPOPUP, MENUSELECT, MENUCHAR, ENTERIDLE, QUERYUISTATE, CTLCOLORMSGBOX, CTLCOLOREDIT, CTLCOLORLISTBOX, CTLCOLORBTN, CTLCOLORDLG, CTLCOLORSCROLLBAR, CTLCOLORSTATIC, MOUSEFIRST, MOUSEMOVE, , LBUTTONDOWN, LBUTTONUP, LBUTTONDBLCLK, RBUTTONDOWN, RBUTTONUP, RBUTTONDBLCLK, MBUTTONDOWN, MBUTTONUP, MBUTTONDBLCLK, MOUSEWHEEL, MOUSELAST, PARENTNOTIFY, ENTERMENULOOP, EXITMENULOOP, NEXTMENU, SIZING, CAPTURECHANGED, MOVING, POWERBROADCAST, DEVICECHANGE, IME_SETCONTEXT, IME_NOTIFY, IME_CONTROL, IME_COMPOSITIONFULL, IME_SELECT, IME_CHAR, IME_KEYDOWN, IME_KEYUP, MDICREATE, MDIDESTROY, MDIACTIVATE, MDIRESTORE, MDINEXT, MDIMAXIMIZE, MDITILE, MDICASCADE, MDIICONARRANGE, MDIGETACTIVE, MDISETMENU, ENTERSIZEMOVE, EXITSIZEMOVE, DROPFILES, MDIREFRESHMENU, MOUSEHOVER, MOUSELEAVE, CUT, COPY, PASTE, CLEAR, UNDO, RENDERFORMAT, RENDERALLFORMATS, DESTROYCLIPBOARD, DRAWCLIPBOARD, PAINTCLIPBOARD, VSCROLLCLIPBOARD, SIZECLIPBOARD, ASKCBFORMATNAME, CHANGECBCHAIN, HSCROLLCLIPBOARD, QUERYNEWPALETTE, PALETTEISCHANGING, PALETTECHANGED, HOTKEY, PRINT, PRINTCLIENT, HANDHELDFIRST, HANDHELDLAST, AFXFIRST, AFXLAST, PENWINFIRST, PENWINLAST, APP, USER

wparam - Any integer that will be passed as the WPARAM of the message. If it is missing, then it is 0 by default.

lparam - Any integer that will be passed as the LPARAM of the message. If it is missing, then it is 0 by default.

Example:

<PostMessageAction Message="CLOSE" ActivationState="Down" />

----------------
ShowWindowAction
----------------
This Action is used to change the state of the current window, such as maximizing or minimizing. It has the following attributes:

Type - The state in which to display the window.

OnlyIf - A conditional to only show the state if the window is already in this state. (Optional)

IfAlreadyInState - A backup state to show the window in if it is already in the state defined in "Type". (Optional)

Valid values for all 3 attributes are: HIDE, NORMAL, MAXIMIZE, SHOWNOACTIVATE, SHOW, MINIMIZE, SHOWMINNOACTIVE, SHOWNA, RESTORE, SHOWDEFAULT, FORCEMINIMIZE

Example:

<ShowWindowAction Type="MAXIMIZE" IfAlreadyInState="RESTORE" ActivationState="Down" />

-----------
SleepAction
-----------
This Action causes Firefly to stop execution of the series of Actions for the specified amount of time. It has the following attribute:

Sleep - The amount of time in milliseconds to pause execution of the Actions.

Example:

<SleepAction Sleep="1000" />

----------------
SpecialKeyAction
----------------
This Action is used in a group with other SpecialKeyActions in order to execute simultaneous keystrokes such as Ctrl-Shift-S. It has the following attributes:

Type - Determines the keystroke state. Valid values are: Up, Down

Key - The key to send. The valid values can be found here:
http://msdn.microsoft.com/library/de...classtopic.asp

Example, To execute the Ctrl-Shift-S stated above, the following block is required:

<SpecialKeyAction Type="Down" Key="ControlKey" />
<SpecialKeyAction Type="Down" Key="ShiftKey" />
<SpecialKeyAction Type="Down" Key="S" />
<SpecialKeyAction Type="Up" Key="ControlKey" />
<SpecialKeyAction Type="Up" Key="ShiftKey" />
<SpecialKeyAction Type="Up" Key="S" />

---------------
SwitchAppAction
---------------
This Action is used to switch focus to a defined application, and if that application is not currently running, run it. It has the following attributes:

Text - Window text identifier. See Identifiers section for details.

Class - Window class identifier. See Identifiers section for details.

File - Window file identifier. See Identifiers section for details.

Executable - The file to execute in case the application is not already running.

State - The state in which to show the application if it is already running. Valid values are: HIDE, NORMAL, MAXIMIZE, SHOWNOACTIVATE, SHOW, MINIMIZE, SHOWMINNOACTIVE, SHOWNA, RESTORE, SHOWDEFAULT, FORCEMINIMIZE, CLOSE

IfAlreadyShowing - The state in which to put the application if it is already the foreground window. Valid values are: HIDE, NORMAL, MAXIMIZE, SHOWNOACTIVATE, SHOW, MINIMIZE, SHOWMINNOACTIVE, SHOWNA, RESTORE, SHOWDEFAULT, FORCEMINIMIZE, CLOSE

Example:

<SwitchAppAction Text="Firefly" Class="WindowsForms" File="firefly.exe" Executable="C:\Firefly\firefly.exe" State="MAXIMIZE" IfAlreadyShowing="CLOSE" />

-------------------
ToggleFireflyAction
-------------------
Toggles showing and hiding of the Firefly Main Menu. It has no additional attributes.

Example:

<ToggleFireflyAction ActivationState="Down" />

-------------------
ToggleHelpAction
-------------------
Toggles showing and hiding of the Firefly help screen. It has no additional attributes.

Example:

<ToggleHelpAction ActivationState="Down" />

-------------------
GrabFocusAction
-------------------
Grabs keyboard focus for the currently active application. Used to force an application to grab keyboard focus. It has no additional attributes.

Example:

<GrabFocusAction ActivationState="Down" />
-------------------
MouseModeAction
-------------------
Toggles mouse mode. It has no additional attributes.

Example:

<MouseModeAction ActivationState="Down" />
-------------------
PlaySoundAction
-------------------
Plays a sound. It has the following attribute:
Sound: Which sound to play. This can either be one of the sounds defined under the current sound scheme (Move, Select, Home, NoSelect, Cancel) or a path to a sound file.

Example:

<PlaySoundAction ActivationState="DownRepeat" Sound="Move" />
-------------------
MasterVolumeAction
-------------------
Changes the Master Volume. It has the following parameters
Direction - One of the following values:
Down: Decreases master volume 5%
Up: Increases master volume 5%
Mute: Toggles master volume mute

Example:

<MasterVolumeAction ActivationState="DownRepeat" Direction="Down" />

[Leaf]

Hi,

Question about SwitchAppAction In your example:

<SwitchAppAction Text="Firefly" Class="WindowsForms" File="firefly.exe" Executable="C:\Firefly\firefly.exe" State="MAXIMIZE" IfAlreadyShowing="CLOSE" />

Can this be used as part of an action assigned to a key? like this:
- <Actions Button="A" Description="Viewing Mode">
<SwitchAppAction Text="Firefly" Class="WindowsForms" File="firefly.exe" Executable="C:\Firefly\firefly.exe" State="MAXIMIZE" IfAlreadyShowing="CLOSE" />
<KeyAction Keys="^g" />
</Actions>

What I'm trying to do is focus an action on a particular window. Can be done fairly easily in girder but I'd like to just use FF. I'm by no means an advanced user but I thought if i could get some pointers or more examples so i could cut and paste then edit with my own info.

In the above I simply stuck your example in to ask this question.

Thanks
Leaf

[aaronmielke]

Can this be used as part of an action assigned to a key?

You can use any action and as many actions as you want for any key

[aaronmielke]

What I'm trying to do is focus an action on a particular window.

Yes, you can use this action to accomplish that. SwitchAppAction will also start the application if it can't find the application's window.

[Leaf]

Umm Aaron I get nada from the links above. Tried a keyword search but have no idea what to look for.

Looking to get this info:
Keys - This is a series of KeyStrokes that can be mapped to. Valid values can be found here:
http://msdn.microsoft.com/library/d...sclasstopic.asp

Thanks

[SHS]

Here the rigth link Provides methods for sending keystrokes to an application

[rakeshagrawal]

shs- thanks for posting the correct link, I also edited Aaron's original post so the inline links are now correct.

[cncb]

Is there any way to specify the "channel id" so that you can perform different actions for the same button if you are using multiple remotes?

[rakeshagrawal]

hmm interesting question. I think the short answer is no, but let me verify and get back to you. what's your use case? I'm curious to know more about how you are using multiple remotes with the same PC.

[aaronmielke]

He's right, not at this time, though if you can give a thorough and compelling scenario description I'll get right on it.

[cncb]

Well, my scenario will be playing music from different parts of the house. I use JRiver Media Center which has "multi-zone" capability. This means you can route different music through different output ports of your soundcard at the same time. So, I plan to use one remote per zone all controlling the same server pc running Media Center.

Actually, I think Girder will be my best bet but I was just curious if you supported it with your "profiles". You can only control specific zone playback directly in Media Center with windows messages ("SendMessage" plugin in Girder) so I'm not sure it is even possible with your "PostMessageAction". Although maybe the "USER" message would work??

[aaronmielke]

Wow, hardcore. I would also suggest Girder. I don't think you could do it with the profile system because there is no way to specify remote IDs. Maybe I could add that. That way you would just set Firefly to "All Channels" then in the profile specify in each action what channel ID the action is associated with? Would that work fo you?

[cncb]

I think that would work, but I'm not sure it is worth the effort unless other people request it. Most likely I will use Girder since I plan to do some IR control with the FireFly as well. Thanks.

[MarqueIV]

Just a quick question... do all the profiles load when it starts, or do they dynamically load as the tray app detects new applications?

Also, does FireFly's profiles (via direct XML editing) handle system key combinations such as ALT-TAB or CTRL-ALT-DELETE, etc.? Most key emulators don't since they use the SendKeys method which isn't at the system level as opposed to something like the Win32 KEYBD_EVENT which posts messages at the driver level and *does* allow commands such as those. (See MSDN for a reference to the KEYBD_EVENT function.)

Thanks!

Mark

[aaronmielke]

All profiles load. I looked into delay loading them but that didn't really save me much memory overhead. You can fake alt-tab etc. You can not fake control-alt-delete. We use sendinput.