Graphics, drawing, images, and fonts

The Graphics class handles drawing basics, shapes, images, and text. Developers never instantiate it directly; the Codename One API passes it in.

You can gain access to a Graphics object using one of the following methods:

A paint method can be implemented as such:

Solid colors are the starting point. Graphics also understands "paint" objects that describe gradients and other patterns. You can pass an instance of Paint to setColor(Paint) in place of an integer color value to activate a gradient for later fill and draw operations. The LinearGradientPaint class is the most common option and accepts a list of color stops along a line:

The fillLinearGradient() convenience methods (with optional repeat flag) provide a shorthand when you need a two-color gradient without constructing your own Paint object.

Radial gradients are equally straightforward using fillRadialGradient() or fillRectRadialGradient(), which can render circular and rectangular radial transitions respectively. These APIs accept the inner/outer colors, focal point, and spread so you can combine them with linear gradients to build sophisticated backgrounds and lighting effects.

For the full CSS gradient range, Graphics exposes a single fillGradient method that consumes a Gradient value object. Gradient is a Paint subclass with three concrete forms - LinearGradient, RadialGradient, ConicGradient - following the same pattern as the Shape hierarchy:

Gradient carries the cycle method (CYCLE_NONE / CYCLE_REPEAT / CYCLE_REFLECT) for repeating / reflected fills. Each port implements fillGradient via the fastest native shader available - Java2D LinearGradientPaint / RadialGradientPaint on the simulator, LinearGradient / RadialGradient / SweepGradient shaders on Android - and falls back to a software rasterizer that calls Gradient#sampleArgb per pixel where no native shader exists.

Graphics.gaussianBlur(Image, float radius) returns a blurred copy of an image using the platform’s fastest path (Core Image on iOS, RenderScript / RenderEffect on Android, JHLabs GaussianFilter in the simulator). The same blur is reachable from CSS via the filter: blur(<length>) and backdrop-filter: blur(<length>) properties, which are stored on the component’s Style as filterBlurRadius and backdropFilterBlurRadius.

The GlassPane `in Codename One is inspired by the Swing `GlassPane & LayeredPane with a few twists. You tried to imagine how Swing developers would have implemented the glass pane knowing what they do now about painters and Swings learning curve. But first: what’s the glass pane?

A typical Codename One application is essentially composed of 3 layers (this is a gross simplification though), the background painters are responsible for drawing the background of all components including the main form. The component draws its own content (which might overrule the painter) and the glass pane paints last…​

Essentially the glass pane is a painter that allows you to draw an overlay on top of the Codename One application.

Overriding the paint method of a form isn’t a substitute for glasspane as it would appear to work initially, when you enter a Form. For example, when modifying an element within the form that element gets repainted not the entire Form!

If you have a form with a Button and text drawn on top using the Form’s paint method it would get erased whenever the button gets focus.

The glass pane is called whenever a component gets painted, it paints within the clipping region of the component hence it won’t break the rest of the components on the Form which weren’t modified.

You can set a painter on a form using code like this:

Or you can use Java 8 lambdas to tighten the code a bit:

PainterChain allows you to chain many painters together to perform different logical tasks such as a validation painter coupled with a fade out painter. The sample below shows a crude validation panel that allows you to draw error icons next to components while exceeding their physical bounds as is common in many user interfaces

The graphics API provides a high performance shape API that allows drawing arbitrary shapes by defining paths and curves and caching the shape drawn in the GPU.

Shapes and transforms ship with all Codename One’s actively maintained ports (Android, iOS, JavaScript, and desktop/Simulator). Older platforms that have reached end of life may lack these APIs, so keep the guard code shown below if you still target them with legacy builds.

Notice that perspective transform is missing from the desktop/simulator port. No real equivalent to perspective transform in Java SE that you could use.

You can show shape drawing with a simple example of a drawing app, that allows the user to tap the screen to draw a contour picture.

The app works by keeping a GeneralPath in memory, and adding points as Bézier curves. Whenever a point is added, the path is redrawn to the screen.

The center of the app is the DrawingCanvas class, which extends Component:

Conceptually this is basic component. You will be overriding the paintBackground() method to draw the path. You keep a reference to a GeneralPath object (which is the concrete implementation of the Shape interface in Codename One) to store each successive point in the drawing. You also parametrize the stroke width and color.

The implementation of the paintBackground() method (shown above) should be straight forward. It creates a stroke of the appropriate width, and sets the color on the graphics context. Then it calls drawShape() to render the path of points.

The addPoint method is designed to allow you to add points to the drawing. A simple implementation that uses straight lines rather than curves might look like this:

The sample introduces a couple of house-keeping member vars (lastX and lastY) to store the last point that was added that you know whether this is the first tap or a later tap. The first tap triggers a moveTo() call, whereas later taps trigger lineTo() calls, which draw lines from the last point to the current point.

A drawing might look like this:

Your previous implementation of addPoint() used lines for each segment of the drawing. Now make a change to allow for smoother edges by using quadratic curves instead of lines.

Codename One’s GeneralPath class includes two methods for drawing curves:

See the General Path javadocs for the full API.

You will make use of the quadTo() method to append curves to the drawing as follows:

This change should be straight forward except, perhaps, the business with the odd variable. Since quadratic curves require two points (also to the implied starting point), you can’t take the last tap point and the current tap point. You need a point between them to act as a control point. This is where you get the curve from. The control point works by exerting a sort of "gravity" on the line segment, to pull the line towards it. This results in the line being curved. The example uses the odd marker to alternate the control point between positions above the line and below the line.

A drawing from the resulting app looks like:

The DrawingCanvas example is a bit naive in that it assumes that the device supports the shape API. Running this code on a device that doesn’t support the Shape API would draw a blank canvas where the shape was expected to be drawn. You can fall back gracefully if you make use of the Graphics.isShapeSupported() method. For example:

The Graphics class has included limited support for 2D transformations for some time now including scaling, rotation, and translation:

All current Codename One ports expose affine transforms (that’s: scale() and rotate()). Use the following table as a quick reference when deciding whether you need a fallback path.

You can check if a particular Graphics context supports rotation and scaling using the isAffineSupported() method.

For example:

The following sections implement an analog clock component. This will show three key concepts in Codename One’s graphics:

There are three separate things that need to be drawn in a clock:

Your clock will extend the Component class, and override the paintBackground() method to draw the clock as follows:

Before you actually draw anything, take a moment to figure out what values you need to know to draw an effective clock. Minimally, you need two values:

The clock also exposes the following parameters to help customize how it’s rendered:

For the tick marks, you will use a single GeneralPath object, making use of the moveTo() and lineTo() methods to draw each individual tick:

At this point your clock should include a series of tick marks orbiting a blank center as shown below:

The Graphics.drawString(str, x, y) method allows you to draw text at any point of a component. The tricky part here is calculating the correct x and y values for each string so that the number appears in the correct location.

For the purposes of this tutorial, you will use the following strategy. For each number (1 through 12):

Now, you should have a clock with tick marks and numbers as shown below:

The clock will include three hands: Hour, Minute, and Second. You will use a separate GeneralPath object for each hand. For the positioning/angle of each, use the following strategy:

Drawing the Second Hand:

For the "second" hand, you will use a simple line from the clock center to the inside edge of the medium tick mark at the 12 o’clock position:

And you will translate it down slightly so that it overlaps the center. This translation will be performed on the GeneralPath object directly rather than through the Graphics context:

Rotating the Second Hand::

The rotation of the second hand will be performed in the Graphics context through the rotate(angle, px, py) method. This requires you to calculate the angle. The px and py arguments constitute the pivot point of the rotation, which, in your case will be the clock center.

Drawing the Minute And Hour Hands:

The mechanism for drawing the hour and minute hands is largely the same as for the minute hand, with a couple of added complexities though:

The remaining drawing code is as follows:

At this point, you have a complete clock as shown below:

The current clock component is cool, but it’s static. It displays the time at the point the clock was created. You discussed low-level animations in the animation section of the guide, here you will show a somewhat more elaborate example.

To animate your clock so that it updates once per second, you need to do two things:

The animate() method in the AnalogClock class:

This method will be invoked on each "pulse" of the EDT. It checks the last time the clock was rendered and returns true if the clock hasn’t been rendered in the current "time second" interval. Otherwise it returns false. This ensures that the clock will be redrawn when the time changes.

Animations can be started and stopped through the Form.registerAnimated(component) and Form.deregisterAnimated(component) methods. The sample encapsulates these calls in start() and stop() methods in the component as follows:

The code to instantiate the clock, and start the animation would be something like:

Clipping is one of the core tenants of graphics programming, you define the boundaries for drawing and when you exceed said boundaries things aren’t drawn. Shape clipping allows you to clip based on any arbitrary Shape and not a rectangle, this allows some unique effects generated in runtime.

For example: this code allows you to draw a rather complex image of duke:

The Codename One coordinate system follows the example of Swing (and many other - but not all-graphics libraries) and places the origin in the upper left corner of the screen. X-values grow to the right, and Y-values grow downward as illustrated below:

The screen origin is in the top left corner of the screen. Given this information, consider the method call on the Graphics context g:

Where would this rectangle be drawn on the screen?

If you answered something like "10 pixels from the top, and 10 pixels from the left of the screen," you might be right. It depends on whether the graphics has a translation or transform applied to it. If there is currently a translation of (20,20) (that’s: 20 pixels to the right, and 20 pixels down), then the rectangle would be rendered at (30, 30).

You can always find out the current translation of the graphics context using the Graphics.getTranslateX() and Graphics.getTranslateY() methods:

If, also, there is a transform applied that rotates the context 45 degrees clockwise, then the rectangle will be drawn at a 45-degree angle with its top left corner somewhere on the left edge of the screen.

You don’t have to worry about the exact screen coordinates for the things you paint. Most of the time, you will be concerned with relative coordinates.

Usually, when you’re drawing onto a Graphics context, you’re doing so within the context of a Component’s paint() method (or one of its variants). In this case, you don’t care what the exact screen coordinates are of your drawing. You’re concerned with their relative location within the coordinate. You can leave the positioning (and even sizing) of the coordinate up to Codename One. Thank you for reading.

To show this, create a simple component called Rectangle component, that draws a rectangle on the screen. You will use the component’s position and size to dictate the size of the rectangle to be drawn. And you will keep a 5 pixel padding between the edge of the component and the edge of your rectangle:

The result is as follows:

Unlike the Graphics drawXXX primitives, methods for setting transformations, including scale(x,y) and rotate(angle), are always applied in screen coordinates. This can be confusing at first, because you may be unsure whether to provide a relative coordinate or an absolute coordinate for a given method.

The general rule is:

Take your RectangleComponent as an example. Suppose you want to rotate the rectangle by 45 degrees, your first try might look something like:

The behavior of this rotation will vary based on where the component is rendered on the screen. To show this, try to place five of these components on a form inside a BorderLayout and see how it looks:

The result is as follows:

This may not be an intuitive outcome since you drew five rectangle components, but you see a portion of one rectangle. The reason is that the rotate(angle) method uses the screen origin as the pivot point for the rotation. Components nearer to this pivot point will experience a less dramatic effect than components farther from it. In your case, the rotation has caused all rectangles except the first one to be rotated outside the bounds of their containing component, and are therefore being clipped. A more sensible solution for your component would be to place the rotation pivot point somewhere inside the component. That way all the components would look the same. Some possibilities would be:

Top Left Corner:

Center:

You could also use the Graphics.setTransform() class to apply rotations and other complex transformations (including 3D perspective transforms), but that belongs to its own topic as it’s a little bit more complex.

Up to this point you’ve relied on the per-pixel alpha stored in images and gradients. Graphics also lets you apply a global alpha multiplier to every draw call by using setAlpha(int) or concatenateAlpha(int) after checking isAlphaSupported(). Both methods accept values from 0 (fully transparent) to 255 (fully opaque) and remain active until you change them again. concatenateAlpha() is especially handy when you need to temporarily fade a component because it returns the previous alpha so you can restore it later.

Anti-aliasing can likewise be toggled at runtime. Call isAntiAliasingSupported() and isAntiAliasedTextSupported() to discover which hints the current port exposes, then use setAntiAliased(boolean) and setAntiAliasedText(boolean) to opt into smoother edges for shapes and glyphs respectively. These switches make it easy to balance rendering quality versus speed depending on the type of content you draw.

The coordinate system and event handling are tied. You can listen for touch events on a component by overriding the pointerPressed(x,y) method. The coordinates received in this method will be absolute screen coordinates, so you may need to do some conversions on these coordinates before using them in your drawXXX() methods.

For example: a pointerPressed() callback method can look like this:

In this case you translated these points so that they would be relative to the origin of the parent component. This is because the drawXXX() methods for this component take coordinates relative to the parent component.

Codename One has a few image types: loaded, RGB (built-in), RGB (Codename One), Mutable, EncodedImage, SVG, MultiImage, FontImage & Timeline. URLImage, FileEncodedImage, FileEncodedImageAsync, and StorageEncodedImage/Async also exist, and are covered in the IO section.

All image types are seamless to use and will work with drawImage and various image related image APIs for the most part with caveats on performance etc.

Performance and memory wise you should read the section below and be aware of the image types you use. The Codename One designer tries to conserve memory and be "clever" by using EncodedImage. While these are great for low memory you need to understand the complexities of image locking and be aware that you might pay a penalty if you don’t.

Here are the pros/cons and logic behind every image type. This covers the logic of how it’s created:

This is the basic image you get when loading an image from the jar or network using Image.createImage(String), Image.createImage(InputStream) & Image.createImage(byte array, int, int),…​

In some platforms calling getGraphics() on an image like this will throw an exception as it’s immutable). This is true for most other images as well.

This restriction might not apply for all platforms.

The image is stored in RAM based on device logic and should be reasonably efficient in drawing speed. For example, it takes up a lot of RAM.

To calculate the amount of RAM taken by a loaded image you use the following formula:

For example: a 50×100 image will take up 20,000 bytes of RAM.

The logic behind this is simple, every pixel contains 3 color channels and an alpha component hence 3 bytes for color and one for alpha.

There are two types of RGB constructed images that are different from one another but since they’re both technically "RGB image’s" you’re bundling them under the same subsection.

This is a close cousin of the loaded image. This image is created using the method Image.createImage(int array, int, int) and receives the AARRGGBB data to form the image. It’s more efficient than the Codename One RGB image but can’t be modified, at least not on the pixel level.

The goal of this image type is to provide an easy way to render RGB data that isn’t modified efficiently at platform native speeds. It’s technically a standard "Loaded Image" internally.

RGBImage is effectively an AARRGGBB array that can be drawn by Codename One.

On most platforms this is inefficient but for some pixel level manipulations there is no other way.

An RGBImage is constructed with an int array (int[]) that includes width*height elements. You can then change the colors and alpha channel directly within the array and draw the image to any source using standard image drawing APIs.

EncodedImage is the workhorse of Codename One. Images returned from resource files are EncodedImage and many APIs expect it.

The EncodedImage is effectively a loaded image that’s "hidden" and extracted as needed to remove the memory overhead associated with loaded image. When creating an EncodedImage the PNG (or JPEG etc.) is loaded to an array in RAM. Such images are small (relatively) so they can be kept in memory without much overhead.

When image information is needed (pixels) the image is decoded into RAM and kept in a weak/sort reference. This allows the image to be cached for performance and allows the garbage collector to reclaim it when the memory becomes scarce.

Since the fully decoded image can be pretty big (width X height X 4) the ability to store the encoded image can be pretty stark. For example: taking your example above a 50×100 image will take up 20,000 bytes of RAM for a loaded image but an EncodedImage can reduce that to 1kb-2kb of RAM.

When drawing an EncodedImage it checks the weak reference cache and if the image is cached then it’s shown otherwise the image is loaded the encoded image cache it then drawn.

EncodedImage isn’t final and can be derived to produce complex image fetching strategies for example: the URLImage class that can dynamically download its content from the web.

EncodedImage can be instantiated through the create methods in the EncodedImage class. Pretty much any image can be converted into an EncodedImage through the createFromImage(Image, boolean) method.

Multi images don’t physically exist as a concept within the Codename One API so there is no way to actually create them and they’re in no way distinguishable from EncodedImage.

The built-in support for multi images is in the resource file loading logic where a MultiImage is decoded and the version that matches the current DPI is physically loaded. From that point on user code can treat it like any other EncodedImage.

The 9-image borders use multi images by default to keep their appearance more refined on the different DPI’s.

FontImage allows using an icon font as if it was an image. You can specify the character, color and size and then treat the FontImage as if its a regular image. The huge benefits are that the font image can adapt to platform conventions in color and scale to adapt to DPI.

You can generate icon fonts using free tools on the internet such as this. Icon fonts are a simple and powerful technique to create a small, modern applications.

Icon fonts can be created in 2 basic ways the first is explicitly by defining all the elements within the font:

A more common and arguably "correct" way to construct such an icon would be through the Style object. The Style object can provide the color, size and background information needed by FontImage.

There are two versions of this method: the first one expects the Style object to have the correct icon font set to its font attribute. The second accepts a Font object as an argument. The latter is useful for a case where you want to reuse the same Style object that you defined for a general UI element for example: you can set an icon for a Button like this and it will take up the style of the Button:

There are many icon fonts on the web, but the field is rather volatile and constantly changing. For example, you wanted to have built-in icons that would allow you to create better looking demos and built-in components.

That’s why you picked the material design icon font for inclusion in the Codename One distribution. It features a stable core set of icons, that aren’t IP encumbered.

You can use the built-in font directly as demonstrated above but there are far better ways to create a material design icon. To find the icon you want you can check out the material design icon gallery. For example: you used the save icon in the samples above.

To recreate the save icon from above you can do something like:

You can even write the code in a more terse style using:

This will produce the same result for slightly shorter syntax.

Timelines allow rudimentary animation and enable GIF importing using the Codename One Designer. Effectively a timeline is a set of images that can be moved rotated, scaled & blended to provide interesting animation effects. It can be created manually using the Timeline class.

Image masking allows you to manipulate images by changing the opacity of an image according to a mask image. The mask image can be hardcoded or generated dynamically, it’s then converted to a Mask object that can be applied to any image. Notice that the masking process is computationally intensive, it should be done once and cached/saved.

The code below can convert an image to a rounded image:

Notice that this example is simplistic to be self contained. You often recommend that developers ship "ready made" mask images with their application which can allow complex effects on the images.

URLImage is an image created with a URL, it implicitly downloads and adapts the image in the given URL while caching it locally. The typical adapt process scales the image or crops it to fit into the same size which is a hard restriction because of the way URLImage is implemented.

The simple use case is pretty trivial:

Or you can use the similar URLImage.createToFileSystem method instead of the Storage version.

This image can now be used anywhere a regular image will appear, it will initially show the placeholder image and then seamlessly replace it with the file after it was downloaded and stored. Notice that if you make changes to the image itself (for example: the scaled method) it will generate a new image which won’t be able to fetch the actual image.

If the file in the URL contains an image that’s too big it will scale it to match the size of the placeholder precisely!
An option also exists to fail if the sizes don’t match. Notice that the image that will be saved is the scaled image, this means you will have little overhead in downloading images that are the wrong size although you will get some artifacts.

The last argument is powerful, its an interface called URLImage.ImageAdapter and you can implement it to adapt the downloaded image in any way you like. For example: you can use an image mask to automatically create a rounded version of the downloaded image.

To do this you can override:

In the adapter interface and return the processed encoded image. If you do heavy processing (for example: rounded edge images) you would need to convert the processed image back to an encoded image so it can be saved. You would then also want to show that this operation should run asynchronously through the appropriate method in the class.

If you need to download the file instantly and not wait for the image to appear before download initiates you can explicitly invoke the fetch() method which will asynchronously fetch the image from the network. Notice that the downloading will still take time so the placeholder is still required.

The standard createToStorage path doesn’t expose the underlying ConnectionRequest, so attaching an Authorization header (or any other custom header / cookie / timeout) requires the RequestDecorator hook. Two ways to install one:

For per-image overrides (for example one endpoint needs an extra API-version header on top of the global bearer token), use the createToStorage(placeholder, key, url, adapter, RequestDecorator) overload. Per-instance decorators run after the global default so they can override or augment whatever the default set:

When a decorator is installed (global or per-call), URLImage skips the default Util.downloadImageToStorage path and builds a ConnectionRequest inline so the decorator can inspect / mutate it before it’s queued. The legacy path remains the default for back-compat when no decorator is set.

A URLImage can be created with a mask adapter to apply an effect to an image. This allows you to round downloaded images or apply any sort of masking for example: you can adapt the round mask code above as such:

The biggest problem with image download service is with lists. Codename One attacks this issue at the core by integrating URLImage support directly into GenericListCellRenderer which means it will work with MultiList, List & ContainerList. To use this support define the name of the component (name not UIID) to end with _URLImage and give it an icon to use as the placeholder. This is easy to do in the multilist by changing the name of icon to icon_URLImage then using this in the data:

Make sure you also set a "real" icon to the entry in the GUI builder or in handcoded applications. This is important since the icon will be implicitly extracted and used as the placeholder value. Everything else should be handled automatically. You can use setDefaultAdapter & setAdapter on the generic list cell renderer to install adapters for the images. The default is a scale adapter although you might change that to scale fill in the future:

The createListEntry method then looks like this:

Codename One includes a charting toolkit in the com.codename1.charts package that’s designed to integrate with regular UI layouts. Charts are drawn by creating an appropriate dataset and renderer pair, instantiating the matching chart view class, and wrapping it in a ChartComponent it can be added to a form:

The following classes are available for different kinds of visualisations: