PureBasic objects

Introduction

The purpose of this section is to describe the behavior, creation, and handling of objects in PureBasic. For the demonstration, we will use the Image object, but the same logic applies to all other PureBasic objects. When creating an Image object, we can do it in two ways: indexed and dynamic.

I. Indexed numbering

The static, indexed way, allows you to reference an object by a predefined numeric value. The first available index number is 0 and subsequent indexes are allocated sequentially. This means that if you use the number 0 and then the number 1000, 1001 indexes will be allocated and 999 (from 1 to 999) will be unused, which is not an efficient way to use indexed objects. If you need a more flexible method, use the dynamic way of allocating objects, as described in section II. The indexed way offers several advantages:

- Easier handling, since no variables or arrays are required.
- 'Group' processing, without the need to use an intermediate array.
- Use the object in procedures without declaring anything in global (if using a constant or a number).
- An object that is associated with an index is automatically freed when reusing that index.

The maximum index number is limited to an upper bound, depending of the object type (usually from 5000 to 60000). Enumerations are strongly recommended if you plan to use sequential constants to identify your objects (which is also recommended).

Example

  CreateImage(0, 640, 480) ; Create an image, the n°0
  ResizeImage(0, 320, 240) ; Resize the n°0 image

Example

  CreateImage(2, 640, 480) ; Create an image, the n°2
  ResizeImage(2, 320, 240) ; Resize the n°2 image
  CreateImage(2, 800, 800) ; Create a new image in the n°2 index, the old one is automatically free'ed

Example

  For k = 0 To 9
    CreateImage(k, 640, 480) ; Create 10 different images, numbered from 0 to 9
    ResizeImage(k, 320, 240) ; Create a new image in the n°2 index, the old one is automatically free'ed
  Next

Example

  #ImageBackground = 0
  #ImageButton     = 1

  CreateImage(#ImageBackground, 640, 480) ; Create an image (n°0)
  ResizeImage(#ImageBackground, 320, 240) ; Resize the background image
  CreateImage(#ImageButton    , 800, 800) ; Create an image (n°1)

II. Dynamic numbering

Sometimes, indexed numbering isn't very handy to handle dynamic situations where we need to deal with an unknown number of objects. PureBasic provides an easy and complementary way to create objects in a dynamic manner. Both methods (indexed and dynamic) can be used together at the same time without any conflict. To create a dynamic object, you just have to specify the #PB_Any constant instead of the indexed number, and the dynamic number will be returned as result of the function. Then just use this number with the other object functions in the place where you would use an indexed number (except to create a new object). This way of object handling can be very useful when used in combination with a list, which is also a dynamic way of storage.

Example

  DynamicImage1 = CreateImage(#PB_Any, 640, 480) ; Create a dynamic image
  ResizeImage(DynamicImage1, 320, 240) ; Resize the DynamicImage1

A complete example of dynamic objects and lists can be found here:

Example

MDI_ImageViewer.pb

Further description and an example of dynamic numbering multiple windows and gadgets can be found in the related 'Beginners chapter'.

Overview of the different PureBasic objects

Different PureBasic objects (windows, gadgets, sprites, etc.) can use the same range of object numbers again. So the following objects can be enumerated each one starting at 0 (or other value) and PureBasic differs them by their type:

- Database
- Dialog
- Entity
- File
- FTP
- Gadget (including the ScintillaGadget())
- Gadget3D
- Image
- Library
- Light
- Mail
- Material
- Menu (not MenuItem(), as this is no object)
- Mesh
- Movie
- Music
- Network
- Node
- Particle
- RegularExpression
- SerialPort
- Sound
- Sound3D
- Sprite
- StatusBar
- Texture
- ToolBar
- Window
- Window3D
- XML