Infenro Home SDK Docs Blah

InfernoTool

Declared in:/boot/home/devel/Inferno-project/Inferno/SDK/Headers/Plugins/InfernoTool.h
Author: YNOP
Version:1.0
Date: Feb 5 2000
Summary:more...


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()
~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()
void 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()
void 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()
BView* 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()
BCursor* 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



Infenro Home SDK Docs Blah

Generated on 12/27/2001
Copyright © 1999-2001 Inferno Dev Team. All rights reserved.