InfernoTool
Tool Addons are the heart of Inferno. They do most
of the work that the user sees. They can be as simple
or complex as they need to be, but remeber that speed
is a issuse, and the longer we spend in the tool the
worse preformance Inferno gets.
Tools are derived from a BView, this is because they
can impiment there 'button' themselfs. What this
means is that the Tool is responsible for the method
in which the user can select or deselfect your tool.
In the case of most tools they will just add a simple
button and thats all. But some tools (such as the
color selector) impiment there views in a totaly
differant way. Its all up to you how you want your
tool to look.
Tools basicly need to do two things. Impiment the
'Button' to select them, and to react to IMouse*
events. the IMose* events are called when a user
clicks on a Document window and your tool is selected.
The Select()/DeSelect() methods are the way Inferno
and your tool communicate. When a users selects
your tool (presses the attached button) you need to
call Select(). This tells Inferno that your tool is
now the current one. When some other tool posts a
Select() all the other tools are Deselected. This
is done by calling there DeSelect() method. Your
should update you view (Make button unselected) to
reprsend this state.
Advanced Tools: Some advanced tool may wish to
create custom buttons/interfaces to there tool.
(like the color selector) This is quite easy.
Just create a custom view and attache it to this
view. If you wish to change the size of your view
you can simple use the ResizeTo/By inside of your
constructor. You also must set the target of any
items to the tool or you will not get there messages
SetTarget(this) inside of AttachedToWindow()
@note Each Tools can only handle particular types of layers.
(some may handle more than one layer type) To tell the
core which layer types you can support you need to export
a commo seperated list:
TOOL_SYMBOLS char LAYER_TYPES_SUPPORTED[] = "Bitmap,Vector";
|
|
or if you can support all layer types (like a color selector)
TOOL_SYMBOLS char LAYER_TYPES_SUPPORTED[] = "*";
|
|
This will tell the core that your Tool can handle Bitmap and
Vector layers. Useing SentEnabled() the core will enable and
disable your tool based upon the current layer type selected
int the document.
If you don't add this the core will assume Bitmap layer
compatibility.
Hook Functions
SaveState()
Select()
DeSelect()
SetEnabled()
Init()
IMouseDown()
IMouseUp()
IMouseMove()
GetConfigView()
GetSettingsView()
GetToolCursor()
GetSupportedSuites()
ResolveSpecifier()
MessageReceived()
Perform()
InfernoTool()
InfernoTool(BMessage *prefs,InfernoCommon *IC)
|
|
Creats a new Tool. The prefs message
is passed in containg this tools last state.
~InfernoTool()
SaveState()
void SaveState(BMessage *prefs)
|
|
Used to save the state of your tool
between boots of Inferno. You should always call
your parents inhereted ver of this.
Select()
This is a method you should call withing your addon
when someone selcts your plugin. There should be
no reason to override this function. However if you
do be sure to call the base class method within yours
as we actually do work in here.
This is the only way to let the core know that the user
wants to select your tool.
DeSelect()
This is called, by the core, when your
addon is nolonger need or when the user switches
to another addon.
This should reset any kind of button or visual cue
to the user that your tool is nolonger the active tool
SetEnabled()
void SetEnabled(bool enable = true)
|
|
Is called by the core to enable or disable
your Tool. You should provide visual cue to the user
that your tool will not work anylonger. You should also
prevent your tool from calling Select().
Init()
void Init(InfernoLayer *Ilay,ScratchView *Scratch,BBitmap *selection, InfernoHistory *IHist)
|
|
Init is called when the user changes
the current working project, or when your tool
is freashly Select()ed. The current layer, ILay,
is passed in for you to work on. A scratch view is
provided (BView like draw methods) if you need to
provide any in-document temporary drawing for aid in
useing your tool.
Selection should always be checked to see if you
are allowed to draw to particular pixel. Selection
uses a grey scale bitmap (values from 0-255) to provide
for soft selections. Helper.h provides a is_in_selection()
method that will return true if the pixel is in selction.
(actually it returns the selection value where 255 is
fully selected and 0 is not selected)
Due plugin base nature of Inferno and the fact that
tool can work in many ways, we require that you
manage Undo data from withing your Tool. This however
is simple useing the IHist class.
IHist->BeginHistoryGroup("MyToolName");
IHist->Save(ILay,dirtyRect);
... // Now draw to the dirtyRect
ICommon->UpdateCanvas(dirtyRect); // Refresh view
IHist->EndHistoryGroup();
|
|
You are alowed to call Save(..) as many times as you like
from withing a Group. If the user have the core to
preform step-undo then each Save() will be undone one
one at a time. Otherwize the entire group will be
undone at once. Most users will have step-undo
turned off.
IMouseDown()
void IMouseDown(BPoint BPoint,uint32 button)
|
|
Called by the core when the user
mouse downs in his/her current document. The point
can exist outside the actuall document view (ie -100,100 is valid)
The point is represented in Document space, thue
you don't need to do any convertions fo zoom factor.
As a conviniounce we have included the button state
IMouseUp()
void IMouseUp(BPoint BPoint,uint32 button)
|
|
Called when the user mouses up in the
current document. Again point is withing document
space and can exist outside its bounds.
IMouseMove()
void IMouseMove(BPoint BPoint,uint32 button)
|
|
This is most likely where most of the
work of you Tool will fall. Like its Up/Down brothers
Move gets called by the core when the user moves
the mouse withing the current project.
The most common way of doing this is a bool drag variable
that is set from within Up/Down. Calling BeginGroup()
frome witing Down and EndGroup() withing Up and calling
Save() and UpdateCanves() here withing Move.
GetConfigView()
This is the View that gets made and attached to a
Tool config window when your tool gets selected. These are things like
current settings and such.
GetSettingsView()
void GetSettingsView(BView *v)
|
|
Settings is the view that comes up in the preferances
box under Infernos prefs pannel. This is used to
save gloable defualts for the Tool and to present
Copyright/Author/Version info. This view is owned
by the core and will be deleted for you.
Genaricly you can add our default view makeup
Its give the basics, and provids a email link
BRect Temp = ConfigView->Bounds();
#if (B_BEOS_VERSION > B_BEOS_VERSION_5)
ConfigView->SetViewUIColor(B_UI_PANEL_BACKGROUND_COLOR);
#else
ConfigView->SetViewColor(ui_color(B_PANEL_BACKGROUND_COLOR));
#endif
Temp.left+=5;
Temp.top+=15;
Temp.bottom = Temp.top + 15;
BStringView* view=new BStringView(Temp,"StringView","Version YOUR_VER_NUM");
ConfigView->AddChild(view);
Temp.top=Temp.bottom+4;
Temp.bottom=Temp.top+14;
view= new BStringView(Temp,"StringView","By YOUR_NAME ");
view->ResizeToPreferred();
ConfigView->AddChild(view);
Temp.left = view->Frame().right;
URLView *email = new URLView(Temp,"StringView", "(YOUR_EMAIL_ADDRESS)","YOUR_EMAIL_ADDRESS");
email->SetViewColor(ui_color(B_PANEL_BACKGROUND_COLOR));
email->SetHoverEnabled( false );
email->SetUnderlineThickness(0);
email->AddAttribute( "META:name", "YOUR_NAME" );
email->AddAttribute( "META:nickname", "YOUR_NICK" );
email->AddAttribute( "META:company", "YOUR_COMPANY" );
email->AddAttribute( "META:url", "http://WWW.YOUR_HOME_PAGE.COM/" );
email->AddAttribute( "META:country", "YOUR_COUNTRY" );
email->ResizeToPreferred();
ConfigView->AddChild(email);
|
|
That it .. have fun...
GetToolCursor()
Tools like haveing unique cursors for some reason
so here is a simple way for the system to grab the
cursor your tool thinks is kewl and make it current.
GetSupportedSuites()
status_t GetSupportedSuites(BMessage *message)
|
|
See BLooper::GetSupportedSuites()
ResolveSpecifier()
BHandler* ResolveSpecifier(BMessage *message,int32 index,BMessage *specifier,int32 what,const char *property)
|
|
See BLooper::ResolveSpecifier()
MessageReceived()
void MessageReceived(BMessage *msg)
|
|
Inferno support Be scripting useing
BMessages and the specifier stack. If your not
used to this, it can be sorta confusing. To make
it a little simple here a sample from the Pencil Tool
The hey command line would look something like this. DO is
short for B_EXECUTE_PROPERTY. The core provides a way (of Tool)
to access each tool to make life simple. When it gest passed
down to us (the Tool) the property, of DO, is "Line" (something that
we export via ::GetSupportedSuites() method.
hey Inferno DO Line of Tool DirectPencilTool with start='BPoint(10,10)' and end='BPoint(20,12)'
|
|
To handle this we must impiment this type of code in ::MessageRecived()
int32 i = 0;
int32 what = 0;
BMessage specifier;
char *property = NULL;
...
switch(msg->what){
case B_EXECUTE_PROPERTY:
msg->GetCurrentSpecifier(&i,&specifier,&what,(const char **)&property);
if(strcmp(property,"Line") == 0){
BPoint s,e;
if(msg->FindPoint("start",&s) != B_OK){
break;
}
if(msg->FindPoint("end",&e) != B_OK){
break;
}
...
// here is where we actaull run the code.
}
break;
...
default:
// Always remeber to do this
ToolAddon::MessageReceived(msg);
}
|
|
Thats basicly all we need to do. You should check other
propertyes if you have them. (all the line tool can DO is
draw a line that that all we need)
Perform()
status_t Perform(perform_code d, void *arg)
|
|
Reserved for the Future
Generated on 12/27/2001
Copyright © 1999-2001 Inferno Dev Team. All rights reserved.