OSL ‐ UI Elements

Basics

• Rendering Frequency: UI is rendered once every frame; this is non-negotiable within the system.

Icon Info

Icons are sourced from files using either the file name or raw icon data.

Colour Commands

• colour #hexcode or c #hexcode: Sets the current colour for subsequent UI elements.

• OSL supports hexadecimal colours and single-value RGB colours.

  Example:

  colour #3498db
  c #3498db
  

Main UI Elements

Thank you for the clarification. Here's an updated version of the documentation for the square command:

---

Square

The square command draws a centered rectangle with specified dimensions and border weight on the draw cursor.

Syntax:

square px-width px-height border_weight 0/1 invisible?

Parameters:

• px-width: The width of the square in pixels.
• px-height: The height of the square in pixels.
• border_weight: The thickness of the square's border.
• 0 (required): If you want to set a square to be invisible and to use it as a hitbox, you need this item in the command
• invisible? (optional): Specifies whether the square is invisible. If omitted, defaults to 1 (visible).

Example:

square 100 50 5 0 1

In this example:

• A square with a width of 100 pixels, height of 50 pixels, and a border thickness of 5 pixels is drawn.
• The square is centered on the draw cursor.
• The square is set to be invisible (0).

Additional Notes:

• The invisible parameter determines the visibility of the square. It defaults to visible (1).
• The 0 before invisible? is required for compatibility purposes.

---

Icon

The icon command renders a single ".icn" file that can be created locally on your account or pulled from the system.

Functionality

The icon command allows you to display icons within your OSL application. These icons can be sourced from files in the system's Icons folder, specified by their names, or created using raw icon data directly within the command.

Syntax

icon "code/name" size

Parameters

• "code/name": Specifies the name of the icon file or provides raw icon code for rendering.
• size: Sets the multiplier for the size of the icon to be rendered. (1 indicates the original size of the icon)

Color Modifier

You can modify the color of the icon using a modifier syntax:

icon "code/name" size : c#fff

Icon Creation Recommendations

It's recommended to keep all icon data inside the application and avoid referencing locally created icons. This ensures consistent access to icons across different users.

Examples

1. Display an icon named "my_icon" with a size multiplier of 1:

   icon "my_icon" 1
   

2. Draw an "X" icon using raw icon code and set its size to 2:

   icon "c #fff line -10 10 10 -10 line -10 -10 10 10" 2
   

3. Display an icon using an array of icon data and set its color to white (#fff):

   icon ["c","#fff","line","-10","10","10","-10","line","-10","-10","10","10"] 1 : c#fff
   

Notes

• Ensure that icon files are accessible to all users by storing them within the application rather than locally.

// Define the icon code as a variable
my_icon_code = ["c","#fff","line","-10","10","10","-10","line","-10","-10","10","10"]

// Render the icon using the variable
icon my_icon_code 2

In this example:

• We define an icon code as a variable named my_icon_code.
• The icon code is specified as an array containing instructions to draw the icon.
• Later, we use the icon command and pass the my_icon_code variable as the icon data. We also set the size multiplier to 2 to make the icon larger.

This approach allows you to store icon data directly within your application's script, ensuring accessibility to all users without relying on external files or resources.

---

Text

• Command:

  • text "text-to-draw" size

• Function:

  • Renders text at the draw cursor with a specified size.

• Parameters:

  • "text-to-draw": The text string to be rendered.
  • size: The size of the text to be rendered.

• Example:

  text "Hello, World!" 16
  

• Explanation:

  • In this example, the text "Hello, World!" is rendered at the current draw cursor position with a font size of 16.
  • The text command allows for direct rendering of text strings on the screen.
  • Additionally, the text command can be used to set the font for subsequent text rendering by providing the URL or file path of a text file containing font data along with the "setfont" parameter.

This command provides a simple and effective way to display text within the UI, allowing for customization of text appearance and font selection when needed.

---

Image

The image command renders an image from a raw URL with optional width and height specifications.

Load an image indirectly (more performant for bigger image urls or "data:" urls)

image "load" "data" "name"

Example:

image "load" "data:url stuff goes here" "test_image"
// put before mainloop to ensure its only loaded once

mainloop:
image "test_image" 200
// render the loaded image at very low performance cost

Syntax:

image "url" width_in_pixels height_in_pixels

Parameters:

• "url": The raw URL of the image to be rendered.
• width_in_pixels (optional): The width of the rendered image in pixels. If omitted, the image will resize to fit its width correctly, and its height will adjust accordingly to maintain the original aspect ratio.
• height_in_pixels (optional): The height of the rendered image in pixels. If omitted, the image will stretch or shrink to match the specified width, preserving its aspect ratio.

Example:

image "https://example.com/image.jpg" 120 80

In this example, an image from the specified URL is rendered with a width of 120 pixels and a height of 80 pixels.

Additional Notes:

• The image command supports raw image URLs and can render images from web sources.
• There is no maximum limit on the size of the image that can be rendered.
• If the image fails to load or if the URL is inaccessible, a "not loaded" placeholder image will be displayed.
• Images can be positioned on the screen using the draw cursor and rotated using direction commands.
• While data URLs can be used with the image command, it's not recommended due to potentially large file sizes.
• Images with alpha channels (transparency) are supported and rendered appropriately.
• Images can be dynamically changed during runtime, similar to other UI elements.

5. Toggle:

   • toggle id size
   • Function: Draws a toggle switch.

   Example:

   toggle myToggle 15
   

All of the above set the clicked, touching_mouse, and onclick variables

6. Slider

   • slider width height id
   • Function: Draws a slider. Example:

   slider 200 20 volumeSlider
   

7. Bar

   • bar width height rounding percent
   • Function: Draws a progress bar.

   Example:

   bar 300 10 5 0.75
   

8. Input

   • input px-width px-height "input_id" "default_text" border_weight text_colour
   • Function: Renders an input field.

   Example:

   input 300 20 "test" "type here!" 10 #fff
   

• You can make a password input that looks like this: (Requires v4.6.4 or later)
  
  by changing the input command and doing "hidden.input_id" instead of "input_id" THIS INPUT FUNCTIONS THE EXACT SAME AND THE "hidden." doesn't get used in the input's variable.

To get the value from an input, use the variable "input_" with the id you put for the input at the end.

Example:

input 300 20 "test" "type here!" 10 #fff
if input_test == "hello" (
  say "hello to you too!"
)

Triangle

• Command:

  • triangle point1_x point1_y point2_x point2_y point3_x point3_y border_weight

• Function:

  • Draws a triangle with specified vertices on the draw cursor.

• Parameters:

  • point1_x: x-coordinate of the first vertex.
  • point1_y: y-coordinate of the first vertex.
  • point2_x: x-coordinate of the second vertex.
  • point2_y: y-coordinate of the second vertex.
  • point3_x: x-coordinate of the third vertex.
  • point3_y: y-coordinate of the third vertex.
  • border_weight: Thickness of the triangle's border.

• Example:

  triangle 10 20 30 40 50 60 2
  

  In this example, a triangle is drawn with vertices at (10, 20), (30, 40), and (50, 60), with a border thickness of 2. The vertices are offset by the xy of the triangle element

• Note:

  • The triangle element is not clickable. It serves as a visual element without interactive functionality.

This command allows you to create triangles with specific vertices, providing flexibility in designing geometric shapes within the UI.

Other UI

• hitbox width height checkx checky: Acts like a hidden square for collision detection.

  • hitbox "hide" and hitbox "show" allow showing/hiding hitboxes.

  Example:

  goto 0 0
  hitbox 50 50 mouse_x mouse_y
  if collided (
    log "mouse pointer is near the middle of the window"
  )
  

Pen

The pen draws a line behind the draw cursor.

• pen "down"/"up": Lifts or lowers the pen.

• pen "size" pen-size: Sets the size of the pen.

  Example:

  pen "down"
  

Image Manipulation (v4.2.7 and above)

Stretch

• stretch "x" 100: Sets the width of the image to its normal width.

• stretch "y" 50: Sets the height of the image to half its normal height.

  Example:

  stretch "x" 120
  
  stretch [120,100]
  // x then y if you use an array

Rotate

• direction 90: Points right.
• direction -45: Points top left.
• turnleft 10: Changes direction by 10 degrees counterclockwise.
• turnright 20: Changes direction by 20 degrees clockwise.
• pointat x y: Points the draw cursor towards a specific x y position on the window

Example:

direction 45