QSplitter Class
La clase QSplitter implementa un widget divisor. Más información...
| Encabezado: | #include <QSplitter> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredan: | QFrame |
Propiedades
- childrenCollapsible : bool
- handleWidth : int
- opaqueResize : bool
- orientation : Qt::Orientation
Funciones públicas
| QSplitter(QWidget *parent = nullptr) | |
| QSplitter(Qt::Orientation orientation, QWidget *parent = nullptr) | |
| virtual | ~QSplitter() |
| void | addWidget(QWidget *widget) |
| bool | childrenCollapsible() const |
| int | count() const |
| void | getRange(int index, int *min, int *max) const |
| QSplitterHandle * | handle(int index) const |
| int | handleWidth() const |
| int | indexOf(QWidget *widget) const |
| void | insertWidget(int index, QWidget *widget) |
| bool | isCollapsible(int index) const |
| bool | opaqueResize() const |
| Qt::Orientation | orientation() const |
| void | refresh() |
| QWidget * | replaceWidget(int index, QWidget *widget) |
| bool | restoreState(const QByteArray &state) |
| QByteArray | saveState() const |
| void | setChildrenCollapsible(bool) |
| void | setCollapsible(int index, bool collapse) |
| void | setHandleWidth(int) |
| void | setOpaqueResize(bool opaque = true) |
| void | setOrientation(Qt::Orientation) |
| void | setSizes(const QList<int> &list) |
| void | setStretchFactor(int index, int stretch) |
| QList<int> | sizes() const |
| QWidget * | widget(int index) const |
Funciones públicas reimplementadas
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Señales
| void | splitterMoved(int pos, int index) |
Funciones protegidas
| int | closestLegalPosition(int pos, int index) |
| virtual QSplitterHandle * | createHandle() |
| void | moveSplitter(int pos, int index) |
| void | setRubberBand(int pos) |
Funciones protegidas reimplementadas
| virtual void | changeEvent(QEvent *ev) override |
| virtual void | childEvent(QChildEvent *c) override |
| virtual bool | event(QEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *) override |
Descripción detallada
Un divisor permite al usuario controlar el tamaño de los widgets secundarios arrastrando el límite entre ellos. Un único divisor puede controlar cualquier número de widgets. El uso habitual de un QSplitter es crear varios widgets y añadirlos mediante insertWidget() o addWidget().
El siguiente ejemplo muestra un ` QListView`, un ` QTreeView` y un ` QTextEdit ` uno al lado del otro, con dos controladores de divisor:
QSplitter *splitter = new QSplitter(parent);
QListView *listview = new QListView;
QTreeView *treeview = new QTreeView;
QTextEdit *textedit = new QTextEdit;
splitter->addWidget(listview);
splitter->addWidget(treeview);
splitter->addWidget(textedit);Si un widget ya se encuentra dentro de un QSplitter cuando se llama a insertWidget() o addWidget(), se desplazará a la nueva posición. Esto puede utilizarse para reordenar los widgets en el divisor más adelante. Puedes utilizar indexOf(), widget() y count() para acceder a los widgets que hay dentro del divisor.
Un QSplitter predeterminado distribuye sus elementos secundarios horizontalmente (uno al lado del otro); puedes utilizar setOrientation(Qt::Vertical) para distribuir sus elementos secundarios verticalmente.
Por defecto, todos los widgets pueden tener el tamaño que el usuario desee, dentro de los límites de minimumSizeHint() (o minimumSize()) y maximumSize() de los widgets.
QSplitter redimensiona sus elementos hijos de forma dinámica de forma predeterminada. Si prefieres que QSplitter redimensione los elementos hijos solo al final de una operación de redimensionamiento, llama a setOpaqueResize(false).
La distribución inicial del tamaño entre los widgets se determina multiplicando el tamaño inicial por el factor de estiramiento. También puede utilizar setSizes() para establecer los tamaños de todos los widgets. La función sizes() devuelve los tamaños establecidos por el usuario. Como alternativa, puede guardar y restaurar los tamaños de los widgets desde un QByteArray utilizando saveState() y restoreState() respectivamente.
Al aplicar hide() a un elemento secundario, su espacio se distribuirá entre los demás elementos secundarios. Se restablecerá al volver a aplicar show() sobre él.
Nota: No se admiteañadir un « QLayout » a un QSplitter (ni mediante « setLayout()» ni haciendo que el QSplitter sea padre del « QLayout »); utilice en su lugar « addWidget()» (véase el ejemplo anterior).
Consideraciones de seguridad
La función restoreState() deserializa un blob binario versionado que describe los tamaños y la orientación de los elementos hijos del splitter. Se validan el número mágico y la versión del formato, pero los campos individuales no se someten a ninguna otra comprobación de validez una vez aceptada la estructura externa.
Solo se debe pasar a ` restoreState()` un ` QByteArray ` que haya sido generado previamente por ` saveState()` y guardado por la misma versión —o una compatible— de la aplicación, normalmente mediante ` QSettings`. No se debe llamar a ` restoreState()` con datos de origen desconocido o no fiable, como un archivo descargado de la red, un archivo de configuración sincronizado o compartido, o datos proporcionados por otra aplicación que pueda estar comprometida.
Véase también QSplitterHandle, QHBoxLayout, QVBoxLayout y QTabWidget.
Documentación de propiedades
childrenCollapsible : bool
Esta propiedad determina si el usuario puede reducir el tamaño de los widgets secundarios hasta el valor 0
Por defecto, los elementos secundarios se pueden contraer. Es posible activar y desactivar la contracción de elementos secundarios individuales mediante setCollapsible().
Funciones de acceso:
| bool | childrenCollapsible() const |
| void | setChildrenCollapsible(bool) |
Véase también setCollapsible().
handleWidth : int
Esta propiedad contiene el ancho de los controladores del divisor
Por defecto, esta propiedad contiene un valor que depende de la plataforma del usuario y de sus preferencias de estilo.
Si se establece handleWidth en 1 o 0, el área de selección real se ampliará hasta solaparse unos pocos píxeles con los widgets correspondientes.
Funciones de acceso:
| int | handleWidth() const |
| void | setHandleWidth(int) |
opaqueResize : bool
Devuelve ` true ` si se cambia el tamaño de los widgets de forma dinámica (opaca) mientras se mueve interactivamente el separador. En caso contrario, devuelve ` false`.
El comportamiento predeterminado al cambiar el tamaño depende del estilo (viene determinado por la indicación de estilo SH_Splitter_OpaqueResize). Sin embargo, se puede anular llamando a setOpaqueResize()
Funciones de acceso:
| bool | opaqueResize() const |
| void | setOpaqueResize(bool opaque = true) |
Véase también QStyle::StyleHint.
orientation : Qt::Orientation
Esta propiedad define la orientación del divisor
Por defecto, la orientación es horizontal (es decir, los widgets se disponen uno al lado del otro). Las orientaciones posibles son Qt::Horizontal y Qt::Vertical.
Funciones de acceso:
| Qt::Orientation | orientation() const |
| void | setOrientation(Qt::Orientation) |
Véase también QSplitterHandle::orientation().
Documentación de funciones de miembro
[explicit] QSplitter::QSplitter(QWidget *parent = nullptr)
Crea un separador horizontal pasando el argumento « parent » al constructor « QFrame ».
Véase también setOrientation().
[explicit] QSplitter::QSplitter(Qt::Orientation orientation, QWidget *parent = nullptr)
Crea un divisor con los valores proporcionados en orientation y parent.
Véase también setOrientation().
[virtual noexcept] QSplitter::~QSplitter()
Elimina el divisor. Se borran todos los elementos secundarios.
void QSplitter::addWidget(QWidget *widget)
Añade el elemento « widget » indicado a la disposición del divisor, después de todos los demás elementos.
Si el widget ya se encuentra en el separador, se moverá a la nueva posición.
Nota: El divisor asume la propiedad del widget.
Véase también insertWidget(), widget() y indexOf().
[override virtual protected] void QSplitter::changeEvent(QEvent *ev)
Reimplementa: QFrame::changeEvent(QEvent *ev).
[override virtual protected] void QSplitter::childEvent(QChildEvent *c)
Reimplementa: QObject::childEvent(QChildEvent *event).
Indica al divisor que el widget hijo descrito por c se ha insertado o eliminado.
Este método también se utiliza para gestionar la situación en la que se crea un widget con el divisor como padre, pero sin añadirlo explícitamente mediante insertWidget() o addWidget(). Esto se hace por motivos de compatibilidad y no es la forma recomendada de colocar widgets en un divisor en código nuevo. Por favor, utiliza insertWidget() o addWidget() en código nuevo.
Véase también addWidget() y insertWidget().
[protected] int QSplitter::closestLegalPosition(int pos, int index)
Devuelve la posición válida más cercana a « pos » del widget en « index ».
En el caso de idiomas que se escriben de derecha a izquierda, como el árabe y el hebreo, la disposición de los separadores horizontales se invierte. En ese caso, las posiciones se miden desde el borde derecho del widget.
Véase también getRange().
int QSplitter::count() const
Devuelve el número de widgets que contiene el diseño del separador.
Véase también widget() y handle().
[virtual protected] QSplitterHandle *QSplitter::createHandle()
Devuelve un nuevo controlador de divisor como widget secundario de este divisor. Esta función puede reimplementarse en subclases para permitir el uso de controladores personalizados.
Véase también handle() y indexOf().
[override virtual protected] bool QSplitter::event(QEvent *e)
Reimplementa: QFrame::event(QEvent *e).
void QSplitter::getRange(int index, int *min, int *max) const
Devuelve el rango válido del divisor en index en *min y *max si min y max no son 0.
QSplitterHandle *QSplitter::handle(int index) const
Devuelve el controlador situado a la izquierda (o encima) del elemento en el diseño del divisor en la posición indicada por index, o nullptr si no existe dicho elemento. El controlador del índice 0 siempre está oculto.
En el caso de idiomas que se escriben de derecha a izquierda, como el árabe y el hebreo, la disposición de los separadores horizontales se invierte. El controlador se situará a la derecha del widget en index.
Véase también count(), widget(), indexOf(), createHandle() y setHandleWidth().
int QSplitter::indexOf(QWidget *widget) const
Devuelve el índice, en el diseño del divisor, del elemento « widget » especificado, o -1 si no se encuentra « widget ». Esto también funciona con los identificadores.
Los identificadores se numeran a partir de 0. Hay tantos identificadores como widgets hijos, pero el identificador en la posición 0 siempre está oculto.
Véanse también count() y widget().
void QSplitter::insertWidget(int index, QWidget *widget)
Inserta el elemento « widget » especificado en el diseño del divisor, en la posición indicada index.
Si widget ya se encuentra en el divisor, se moverá a la nueva posición.
Si index es un índice no válido, el widget se insertará al final.
Nota: El divisor asume la propiedad del widget.
Véase también addWidget(), indexOf() y widget().
bool QSplitter::isCollapsible(int index) const
Devuelve « true » si el widget de index es plegable; en caso contrario, devuelve « false ».
[override virtual] QSize QSplitter::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: ` QWidget::minimumSizeHint`.
[protected] void QSplitter::moveSplitter(int pos, int index)
Mueve el borde izquierdo o superior del controlador del separador situado en index lo más cerca posible de la posición pos, que es la distancia desde el borde izquierdo o superior del widget.
En el caso de idiomas que se escriben de derecha a izquierda, como el árabe y el hebreo, la disposición de los separadores horizontales se invierte. En ese caso, ` pos ` es la distancia desde el borde derecho del widget.
Véanse también splitterMoved(), closestLegalPosition() y getRange().
void QSplitter::refresh()
Actualiza el estado del divisor. No debería ser necesario llamar a esta función.
QWidget *QSplitter::replaceWidget(int index, QWidget *widget)
Sustituye el widget del diseño del separador situado en la posición indicada por index por widget.
Devuelve el widget que acaba de ser sustituido si index es válido y widget aún no es un elemento secundario del divisor. En caso contrario, devuelve null y no se realiza ninguna sustitución ni adición.
La geometría del widget recién insertado será la misma que la del widget al que sustituye. También se heredan sus estados «visible» y «colapsado».
Nota: El separador asume la propiedad de widget y establece el padre del widget sustituido en null.
Nota: Dado que ` widget ` introduce ` reparented ` en el divisor, es posible que su ` geometry ` no se establezca de inmediato, sino solo después de que ` widget ` reciba los eventos correspondientes.
Véase también ` insertWidget()` y ` indexOf()`.
[override virtual protected] void QSplitter::resizeEvent(QResizeEvent *)
Reimplementa: ` QWidget::resizeEvent(QResizeEvent *event)`.
bool QSplitter::restoreState(const QByteArray &state)
Restaura la disposición del divisor según lo especificado en ` state `. Devuelve ` true ` si se restaura el estado; en caso contrario, devuelve ` false`.
Normalmente se utiliza junto con ` QSettings ` para restaurar el tamaño de una sesión anterior. A continuación se muestra un ejemplo:
Restaurar el estado del divisor:
QSettings settings;
splitter->restoreState(settings.value("splitterSizes").toByteArray());Si no se consigue restaurar el diseño del divisor, puede deberse a que los datos del array de bytes proporcionado sean inválidos o estén desactualizados.
Véase también saveState().
QByteArray QSplitter::saveState() const
Guarda el estado de la disposición del divisor.
Normalmente se utiliza junto con ` QSettings ` para recordar el tamaño de cara a una sesión futura. Se almacena un número de versión como parte de los datos. A continuación se muestra un ejemplo:
QSettings settings;
settings.setValue("splitterSizes", splitter->saveState());Véase también restoreState().
void QSplitter::setCollapsible(int index, bool collapse)
Establece si el widget secundario situado en index puede colapsarse en collapse.
Por defecto, los widgets secundarios se pueden contraer, lo que significa que el usuario puede reducir su tamaño hasta 0, incluso si tienen un valor distinto de cero en minimumSize() o minimumSizeHint(). Este comportamiento se puede modificar para cada widget llamando a esta función, o de forma global para todos los widgets del divisor estableciendo la propiedad childrenCollapsible.
Véanse también isCollapsible() y childrenCollapsible.
[protected] void QSplitter::setRubberBand(int pos)
Muestra una banda elástica en la posición pos. Si pos es un valor negativo, se elimina la banda elástica.
void QSplitter::setSizes(const QList<int> &list)
Establece los tamaños respectivos de los widgets secundarios en los valores indicados en la propiedad « list ».
Si el divisor es horizontal, los valores establecen el ancho de cada widget en píxeles, de izquierda a derecha. Si el divisor es vertical, se establece la altura de cada widget, de arriba abajo.
Los valores adicionales de la lista « list » se ignoran. Si « list » contiene muy pocos valores, el resultado es indefinido, pero el programa seguirá funcionando correctamente.
El tamaño total del widget divisor no se ve afectado. En su lugar, cualquier espacio adicional o que falte se distribuye entre los widgets según el peso relativo de los tamaños.
Si se especifica un tamaño de 0, el widget será invisible. Se conservan las políticas de tamaño de los widgets. Es decir, un valor inferior a la sugerencia de tamaño mínimo del widget correspondiente se sustituirá por el valor de la sugerencia.
Véase también sizes().
void QSplitter::setStretchFactor(int index, int stretch)
Actualiza la política de tamaño del widget situado en la posición index para que tenga un factor de estiramiento de stretch.
stretch no es el factor de estiramiento efectivo; el factor de estiramiento efectivo se calcula tomando el tamaño inicial del widget y multiplicándolo por stretch.
Esta función se proporciona por comodidad. Es equivalente a
QWidget *widget = splitter->widget(index);
QSizePolicy policy = widget->sizePolicy();
policy.setHorizontalStretch(stretch);
policy.setVerticalStretch(stretch);
widget->setSizePolicy(policy);Véase también setSizes() y widget().
[override virtual] QSize QSplitter::sizeHint() const
Reimplementa: ` QFrame::sizeHint()` const.
QList<int> QSplitter::sizes() const
Devuelve una lista con los parámetros de tamaño de todos los widgets de este divisor.
Si la orientación del divisor es horizontal, la lista contiene el ancho de los widgets en píxeles, de izquierda a derecha; si la orientación es vertical, la lista contiene la altura de los widgets en píxeles, de arriba abajo.
Al pasar estos valores a la función setSizes() de otro divisor, se creará un divisor con el mismo diseño que este.
Ten en cuenta que los widgets invisibles tienen un tamaño de 0.
Véase también setSizes().
[signal] void QSplitter::splitterMoved(int pos, int index)
Esta señal se emite cuando el controlador del divisor situado en una dirección determinada index se ha desplazado hasta la posición pos.
En el caso de idiomas que se escriben de derecha a izquierda, como el árabe y el hebreo, la disposición de los separadores horizontales se invierte. En ese caso, pos es la distancia desde el borde derecho del widget.
Véase también moveSplitter().
QWidget *QSplitter::widget(int index) const
Devuelve el widget situado en la posición « index » del diseño del divisor, o « nullptr » si no existe dicho widget.
Véase también count(), handle(), indexOf() y insertWidget().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.