Manipulator-class

Derived from: none

Declared in: Manipulator.h

Overview

The Manipulator-class is the base for manipulators that do not need any adjustment by the user. The class has two methods that need to be implemented in the subclass that you create. Those functions are ManipulateBitmap and ReturnName. The class also has a utility-function DuplicateBitmap that can be used to duplicate bitmaps.

Constructor and Destructor

Manipulator()

  Manipulator()
Initializes the manipulator.

~Manipulator()

  virtual ~Manipulator()
Does nothing.

Member Functions

ManipulateBitmap()

  virtual  BBitmap*  ManipulateBitmap(BBitmap* original,
    Selection* selection, BStatusBar* status_bar)
This function is implemented by derived classes. The original is the bitmap that should be manipulated. This method can do anything to original except delete it. The method should return a bitmap that contains the manipulated image. This returned bitmap can be original or some other bitmap. The returned bitmap becomes the property of the calling function and should not be freed by the manipulator. If for some reason manipulation cannot be done this function should return NULL. Currently original is always in B_RGB32 color-space and the returned bitmap must also be in B_RGB32 color-space. It is still a good idea to check the color-space of original before manipulating it. The original does not accept BViews and neither should the returned bitmap.

The selection tells what pixels of the image should be manipulated. See instructions on using selections for more details.

The status_bar should be updated with a total delta of one hundred during the manipulation. If the manipulation only lasts for very short time it is probably wise to update the status_bar only once. If the manipulation lasts for long time, it is a good idea to update it for example 20 times during the manipulation with 5 units each time. The part of the code that does the updating should look something like the following: 

  if (time_to_update == TRUE) {		
    BWindow *window = status_bar->Window();
    if (window != NULL) {
      BMessage *a_message;
      a_message = new BMessage(B_UPDATE_STATUS_BAR);
      a_message->AddFloat("delta",update_amount);
      window->PostMessage(a_message,status_bar);
      delete a_message;
    }
    time_to_update = FALSE;
  }

ReturnSettings()

  virtual  ManipulatorSettings*  ReturnSettings()
This function retuns a pointer to instance of class ManipulatorSettings or its subclass. The default version returns NULL. You should not re-imlement this function in any manipulators that are based directly on Manipulator-class. Implementing this function is only meaningful for GUIManipulator-class and its subclasses.

ReturnName()

  virtual  char*  ReturnName()
This function is implemented in subclasses to return a pointer to a string representing the manipulators name. The name should start with an upper-case letter and should be in a form suitable to be used in undo and redo menu items. The returned name should not end with an ellipsis even if the exported add-on name ends with an ellipsis.

DuplicateBitmap()

  protected BBitmap*  DuplicateBitmap(BBitmap* original,
    int32 inset = 0, bool accept_views = FALSE)
This method can be used to make copies of bitmaps. A copy of original is created and then it is returned. If the function fails, it will return NULL or if it runs out of memory it will throw a bad_alloc().

The parameter inset determines how much larger or smaller the copied bitmap will be. If the value is negative, the resulting bitmap will be larger than the original and the edges will be padded to fill the new bitmap. If the parameter is positive, the new bitmap will be smaller than the original.

The parameter accept_views is passed to BBitmap constructor and it determines whether the returned bitmap can accept views or not.