Name
ImageRequest -- prompt the user to select an image (V8.0)
Synopsis
[id] = ImageRequest(id[, type, t])
Library
requester

Platforms
Android only

Function
This function can be used to prompt the user to select an image. The image will then be stored as the brush specified in id. If you specify Nil in the id argument, ImageRequest() will automatically choose an identifier for the brush and return the identifier to you. Alternatively, you can also force this function to return the content URI to the image instead of a brush by setting the FileMode tag to True (see below).

The optional type argument allows you to specify the image source to use when prompting the user for an image. This can currently be set to one of the following predefined constants:

#REQ_GALLERY:
Open the device's gallery and prompt the user to select an image from the gallery.

#REQ_CAMERA:
Open the device's camera and prompt the user to take a picture that will then be returned to your script.

The default mode is #REQ_GALLERY, i.e. ImageRequest() will prompt the user to select an image from the device's gallery.

To find out if this function has failed because the user cancelled the image requester, just use HaveObject() to see if the brush object exists after ImageRequest() returns. If it doesn't exist, the user has cancelled the image requester. See HaveObject for details.

Starting with Hollywood 11, this function accepts an optional table argument that can be used to specify the following additional options:

FileMode:
If this tag is set to True, ImageRequest() will return the path to a file instead of a brush. Note that if you use #REQ_CAMERA, the file will be a temporary file that you should delete when you're done with it. Note that the returned path will usually be a special content URI. See Working with Android URIs for details.

Inputs
id
id for the brush or Nil for auto id selection
type
optional: image source to use; see above for possible modes; defaults to #REQ_GALLERY
t
optional: table argument specifying further options
Results
id
optional: identifier of the brush; will only be returned when you pass Nil as argument 1 (see above); alternatively, this can be a string containing the path to the image (see above)
Example
ImageRequest(1, #REQ_CAMERA)
If HaveObject(#BRUSH, 1)
  DisplayBrush(1, #CENTER, #CENTER)
Else
  NPrint("Requester cancelled!")
EndIf
The code above prompts the user to take a picture with the camera and then displays this picture. It also checks if the requester has been cancelled. 

uri$ = ImageRequest(0, #REQ_CAMERA, {FileMode = True})
If uri$ <> ""
  LoadBrush(1, uri$)
  DisplayBrush(1, 0, 0)
  DeleteFile(uri$)  ; delete temporary file
Else
  NPrint("Requester cancelled!")
EndIf
The code above does the same as the first example but now uses an external file instead of a Hollywood brush.
Show TOC