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 you 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, however, 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 DefaultAdaptiveRuntimeFullScreenStrategy implementation. Yes, it's a long class name, get over it. 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.

This strategy implementation does not have a specific implementation for macOS, but you are free to provide your own.

Using one of the pre-built strategy implementations provided by vlcj is very simple. There are a number of different ways of doing this, depending on how you create your media player, the simplest is:

mediaPlayerComponent = new EmbeddedMediaPlayerComponent();

mediaPlayerComponent.getMediaPlayer().setFullScreenStrategy(
    new DefaultAdaptiveRuntimeFullScreenStrategy(frame)
);

Here, frame is the window in your application that you want to switch in and out of full-screen mode.

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.getMediaPlayer().toggleFullScreen();

Secondly:

mediaPlayerComponent.getMediaPlayer().setFullScreen(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.getMediaPlayer().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 in full-screen mode, and that when you exit full-screen you restore those components again.

For the 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 DefaultAdaptiveRuntimeFullScreenStrategy we implement the provided template methods:

mediaPlayerComponent = new EmbeddedMediaPlayerComponent();

mediaPlayerComponent.getMediaPlayer().setFullScreenStrategy(
    new DefaultAdaptiveRuntimeFullScreenStrategy(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, DefaultFullScreenStrategy. 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.

Summary

This tutorial has shown how to switch your media player into and out of full-screen mode, and how to use a full-screen strategy implementation to hook in to the full-screen process so you can take necessary actions at the appropriate time, like hiding and showing other on-screen controls.