Full Screen

Building on previous tutorials, we will now add full-screen functionality to our media player.

Background Information

Being able to switch from the normal windowed mode to showing video in full-screen should be simple, however it isn't.

Java provides a Full-Screen Exclusive Mode (FSEM) which is supposed to be a platform dependent way of running your Java application in full-screen. The problem is that in practice there are problems across different platforms - for example on some platforms when you try and go into full-screen mode you find that your task bar appears on top of your video, or you might find that your operating system tries to fake full-screen by maximising your window and you still see window decorations (like a close button), and so on.

There is no single approach that will allow for a reliable, common, cross-platform way to implement full-screen applications.

What vlcj provides to help implement an appropriate full-screen solution is a "strategy" pattern whereby the vlcj media player deals only in an abstract interface for entering and exiting full-screen mode - vlcj will take care of invoking the strategy methods at the right time, but a particular strategy implementation (chosen by, or implemented by, you as the application developer) is responsible for the actual code that enters and exits full-screen mode.

You are not on your own here as vlcj provides a number of useful full-screen strategy implementations for you to use or extend as you see fit. If vlcj does not provide a full-screen strategy implementation that is appropriate for you, then you are free to write your own instead and use that.

The most reliable full-screen strategy implementations are those that invoke the native operating system API to enter and exit full-screen mode.

Let's Get Started

You should now already have a basic template for how to create a vlcj application, so this tutorial will no longer duplicate all of the code each time - instead we'll just show the new code fragments.

Choosing a Full-Screen Strategy Implementation

For this tutorial we are going to use the AdaptiveFullScreenStrategy implementation. This particular implementation picks an appropriate strategy to use depending on the run-time operating system. For Linux (or more generally X11) an appropriate native strategy implementation is used (an instance of XFullScreenStrategy), and for Windows a different native strategy implementation is used (an instance of Win32FullScreenStrategy).

None of these implementations use the previously mentioned Full-Screen Exclusive Mode, they instead invoke native operating system API functions.

Using one of the pre-built strategy implementations provided by vlcj is very simple. There are a number of different ways of doing this.

By default, full-screen is not supported for media players or the EmbeddedMediaPlayerComponent.

If you are using EmbeddedMediaPlayerComponent:

mediaPlayerComponent = new EmbeddedMediaPlayerComponent(
    null,
    null,
    new AdaptiveFullScreenStrategy(window),
    null,
    null
);

Here window is your application window or frame that will be made full-screen.

If you are not using the EmbeddedMediaPlayerComponent and are instead using the EmbeddedMediaPlayer directly:

mediaPlayer.fullScreen().strategy(new AdaptiveFullScreenStrategy(window))

Using Full-Screen Mode

With a full-screen strategy in place, you can now very easily switch in and out of full-screen mode - there are two ways to do this:

mediaPlayerComponent.mediaPlayer().fullScreen().toggle();

Secondly:

mediaPlayerComponent.mediaPlayer().fullScreen().set(true);

How you hook this up in your own application is up to you - you can use menus, buttons, actions, keyboard short-cuts and so on.

For some strategy implementations you can also query the full-screen mode - this is not always supported:

mediaPlayerComponent.mediaPlayer().fullScreen().isFullScreen();

Not Quite

If you've tried implementing this so far, you will probably have discovered that it is not only your video surface that goes into full-screen mode, your entire window does - this will include any "furniture" you have on your window like buttons, status bars, menu bars and so on.

You need to make sure that when you enter full-screen you hide the components you don't want in full-screen mode, and that when you exit full-screen you restore those components again.

For this reason, the strategy implementations provide a plug-in point as a pair of template methods that you can override, in the specific case of the AdaptiveFullScreenStrategy we implement the provided template methods:

mediaPlayerComponent.mediaPlayer().fullScreen().strategy(
    new AdaptiveFullScreenStrategy(frame) {
        @Override
        protected void beforeEnterFullScreen() {
            controlsPane.setVisible(false);
            statusBar.setVisible(false);
        }
        @Override
        protected void afterExitFullScreen() {
            controlsPane.setVisible(true);
            statusBar.setVisible(true);
        }
    }
);

In this hypothetical case we simply hide and show some other user interface components at the appropriate time. You might also want to do things like install different keyboard short-cuts when in full-screen mode (like an ESCAPE key binding to exit full-screen mode) and you can use these template methods to dynamically register and un-register things like that.

Other Strategies

vlcj does provide a full-screen strategy implementation that uses the aforementioned Full-Screen Exclusive Mode, ExclusiveModeFullScreenStrategy. You are free to use it but it is not recommended.

If there is no full-screen strategy provided by vlcj that satisfies your own use-cases, you are free to implement your own and easily plug it in.

Caprica Software